foxBMS - Unit Tests  1.5.0
The foxBMS Unit Tests API Documentation
fram_cfg.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2023, 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 fram_cfg.h
44  * @author foxBMS Team
45  * @date 2020-03-05 (date of creation)
46  * @updated 2023-02-03 (date of last update)
47  * @version v1.5.0
48  * @ingroup DRIVERS
49  * @prefix FRAM
50  *
51  * @brief Headers for the configuration for the FRAM module
52  *
53  *
54  */
55 
56 #ifndef FOXBMS__FRAM_CFG_H_
57 #define FOXBMS__FRAM_CFG_H_
58 
59 /*========== Includes =======================================================*/
60 
61 #include "battery_system_cfg.h"
62 
63 #include "fstd_types.h"
64 
65 #include <math.h>
66 #include <stdint.h>
67 
68 /*========== Macros and Definitions =========================================*/
69 
70 /* Header in each entry is made of 4 bytes SPI header + 8 bytes CRC */
71 #define FRAM_CRC_HEADER_SIZE (sizeof(uint64_t))
72 
73 /**
74  * @brief IDs for projects that use a memory layout
75  * @details This enum can be use to differentiate between projects. While an older
76  * version of the same project should be upgradeable, the entry of another
77  * project should be just discarded if a conflict occurs.
78  *
79  * In order for the ID to stay the same it is important that the defined
80  * macros are not changed and that each and every macro has a different
81  * value.
82  */
83 typedef uint16_t FRAM_PROJECT_ID;
84 
85 /** this is the standard main development branch */
86 #define FRAM_PROJECT_ID_FOXBMS_BASELINE ((FRAM_PROJECT_ID)0u)
87 
88 /** fram block identification numbers */
89 typedef enum {
90  FRAM_ACCESS_OK, /* Transaction with FRAM was successful */
91  FRAM_ACCESS_SPI_BUSY, /* SPI busy, transaction with FRAM could not take place */
92  FRAM_ACCESS_CRC_BUSY, /* CRC hardware busy, transaction with FRAM could not take place */
93  FRAM_ACCESS_CRC_ERROR, /* Read CRC does not match with CRC computed on read data */
95 
96 /** configuration struct of database channel (data block) */
97 typedef struct {
98  void *blockptr;
99  uint32_t datalength;
100  uint32_t address;
102 
103 /** fram block identification numbers */
104 typedef enum {
112  FRAM_BLOCK_MAX, /**< DO NOT CHANGE, MUST BE THE LAST ENTRY */
114 
115 /**
116  * @brief Stores the version of the memory layout of the FRAM
117  * @details This struct stores with which memory-layout version the FRAM has
118  * been written. This allows the BMS to recognize an incompatible
119  * memory layout.
120  */
121 typedef struct {
122  FRAM_PROJECT_ID project; /*!< an identifier for the project, it is not
123  intended to migrate between different projects */
124  uint8_t major; /*!< major release version */
125  uint8_t minor; /*!< minor release version */
126  uint8_t patch; /*!< patch release version */
128 
129 /** struct for the FRAM entry of the SBC driver */
130 typedef struct {
131  uint8_t phase;
134 
135 /**
136  * state of charge (SOC). Since SOC is voltage dependent, three different
137  * values are used, min, max and average. SOC defined as a float_t number between
138  * 0.0f and 100.0f (0% and 100%)
139  */
140 typedef struct {
141  float_t minimumSoc_perc[BS_NR_OF_STRINGS]; /*!< minimum SOC */
142  float_t maximumSoc_perc[BS_NR_OF_STRINGS]; /*!< maximum SOC */
143  float_t averageSoc_perc[BS_NR_OF_STRINGS]; /*!< average SOC */
144 } FRAM_SOC_s;
145 
146 /**
147  * state of energy (SOE). Since SOE is voltage dependent, three different
148  * values are used, min, max and average. SOE defined as a float_t number between
149  * 0.0f and 100.0f (0% and 100%)
150  */
151 typedef struct {
152  float_t minimumSoe_perc[BS_NR_OF_STRINGS]; /*!< minimum SOE */
153  float_t maximumSoe_perc[BS_NR_OF_STRINGS]; /*!< maximum SOE */
154  float_t averageSoe_perc[BS_NR_OF_STRINGS]; /*!< average SOE */
155 } FRAM_SOE_s;
156 
157 /** flag to indicate if a deep-discharge in a string has been detected */
158 typedef struct {
159  bool deepDischargeFlag[BS_NR_OF_STRINGS]; /*!< false (0): no error, true (1): deep-discharge detected */
161 
162 /** flag to indicate if insulation ground error has been detected */
163 typedef struct {
164  bool groundErrorDetected; /*!< false (0): no error, true (1): gorund error detected */
166 
167 /**
168  * @brief struct that stores for each task the last violation of timing
169  */
170 typedef struct {
171  /** convenience flag that is set as long as any timing issues are recorded */
173  /** duration that has been recorded when the last violation of timings occurred */
175  /** timestamp that has been recorded when the violating execution of the task has been entered */
177  /** duration that has been recorded when the last violation of timings occurred */
179  /** timestamp that has been recorded when the violating execution of the task has been entered */
181  /** duration that has been recorded when the last violation of timings occurred */
183  /** timestamp that has been recorded when the violating execution of the task has been entered */
185  /** duration that has been recorded when the last violation of timings occurred */
187  /** timestamp that has been recorded when the violating execution of the task has been entered */
189  /** duration that has been recorded when the last violation of timings occurred */
191  /** timestamp that has been recorded when the violating execution of the task has been entered */
194 
195 /*========== Extern Constant and Variable Declarations ======================*/
196 
198 
199 /**
200  * Variables to be stored in FRAM
201  */
202 /**@{*/
204 extern FRAM_SOC_s fram_soc;
205 extern FRAM_SOE_s fram_soe;
210 /**@}*/
211 
212 /*========== Extern Function Prototypes =====================================*/
213 
214 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
215 #ifdef UNITY_UNIT_TEST
216 #endif
217 
218 #endif /* FOXBMS__FRAM_CFG_H_ */
Configuration of the battery system (e.g., number of battery modules, battery cells,...
#define BS_NR_OF_STRINGS
Number of parallel strings in the battery pack.
FRAM_SOC_s fram_soc
Definition: fram_cfg.c:71
FRAM_SYS_MON_RECORD_s fram_sys_mon_record
Definition: fram_cfg.c:78
FRAM_SOE_s fram_soe
Definition: fram_cfg.c:72
FRAM_RETURN_TYPE_e
Definition: fram_cfg.h:89
@ FRAM_ACCESS_SPI_BUSY
Definition: fram_cfg.h:91
@ FRAM_ACCESS_CRC_BUSY
Definition: fram_cfg.h:92
@ FRAM_ACCESS_CRC_ERROR
Definition: fram_cfg.h:93
@ FRAM_ACCESS_OK
Definition: fram_cfg.h:90
FRAM_INSULATION_FLAG_s fram_insulationFlags
Definition: fram_cfg.c:79
uint16_t FRAM_PROJECT_ID
IDs for projects that use a memory layout.
Definition: fram_cfg.h:83
FRAM_BLOCK_ID_e
Definition: fram_cfg.h:104
@ FRAM_BLOCK_ID_DEEP_DISCHARGE_FLAG
Definition: fram_cfg.h:108
@ FRAM_BLOCK_ID_VERSION
Definition: fram_cfg.h:105
@ FRAM_BLOCK_ID_SOC
Definition: fram_cfg.h:106
@ FRAM_BLOCK_ID_SBC_INIT_STATE
Definition: fram_cfg.h:107
@ FRAM_BLOCK_MAX
Definition: fram_cfg.h:112
@ FRAM_BLOCK_ID_SOE
Definition: fram_cfg.h:109
@ FRAM_BLOCK_ID_SYS_MON_RECORD
Definition: fram_cfg.h:110
@ FRAM_BLOCK_ID_INSULATION_FLAG
Definition: fram_cfg.h:111
FRAM_BASE_HEADER_s fram_base_header[FRAM_BLOCK_MAX]
Definition: fram_cfg.c:86
FRAM_DEEP_DISCHARGE_FLAG_s fram_deepDischargeFlags
Definition: fram_cfg.c:77
FRAM_SBC_INIT_s fram_sbcInit
Definition: fram_cfg.c:73
FRAM_VERSION_s fram_version
Definition: fram_cfg.c:70
Definition of foxBMS standard types.
STD_RETURN_TYPE_e
Definition: fstd_types.h:82
uint32_t address
Definition: fram_cfg.h:100
uint32_t datalength
Definition: fram_cfg.h:99
uint8_t phase
Definition: fram_cfg.h:131
STD_RETURN_TYPE_e finState
Definition: fram_cfg.h:132
struct that stores for each task the last violation of timing
Definition: fram_cfg.h:170
uint32_t taskEngineViolatingDuration
Definition: fram_cfg.h:174
uint32_t taskEngineEnterTimestamp
Definition: fram_cfg.h:176
uint32_t task10msViolatingDuration
Definition: fram_cfg.h:182
uint32_t task100msViolatingDuration
Definition: fram_cfg.h:186
uint32_t task100msEnterTimestamp
Definition: fram_cfg.h:188
uint32_t task1msViolatingDuration
Definition: fram_cfg.h:178
uint32_t task100msAlgorithmEnterTimestamp
Definition: fram_cfg.h:192
uint32_t task10msEnterTimestamp
Definition: fram_cfg.h:184
uint32_t task1msEnterTimestamp
Definition: fram_cfg.h:180
uint32_t task100msAlgorithmViolatingDuration
Definition: fram_cfg.h:190
Stores the version of the memory layout of the FRAM.
Definition: fram_cfg.h:121
FRAM_PROJECT_ID project
Definition: fram_cfg.h:122
uint8_t minor
Definition: fram_cfg.h:125
uint8_t major
Definition: fram_cfg.h:124
uint8_t patch
Definition: fram_cfg.h:126