foxBMS  1.3.0
The foxBMS Battery Management System API Documentation
fram_cfg.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2022, 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 2022-05-30 (date of last update)
47  * @version v1.3.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 #include "general.h"
61 
62 #include "battery_system_cfg.h"
63 
64 /*========== Macros and Definitions =========================================*/
65 
66 /* Header in each entry is made of 4 bytes SPI header + 8 bytes CRC */
67 #define FRAM_CRC_HEADER_SIZE (sizeof(uint64_t))
68 
69 /**
70  * @brief IDs for projects that use a memory layout
71  * @details This enum can be use to differentiate between projects. While an older
72  * version of the same project should be upgradeable, the entry of another
73  * project should be just discarded if a conflict occurs.
74  *
75  * In order for the ID to stay the same it is important that the defined
76  * macros are not changed and that each and every macro has a different
77  * value.
78  */
79 typedef uint16_t FRAM_PROJECT_ID;
80 
81 /** this is the standard main development branch */
82 #define FRAM_PROJECT_ID_FOXBMS_BASELINE ((FRAM_PROJECT_ID)0u)
83 
84 /** fram block identification numbers */
85 typedef enum {
86  FRAM_ACCESS_OK, /* Transaction with FRAM was successful */
87  FRAM_ACCESS_SPI_BUSY, /* SPI busy, transaction with FRAM could not take place */
88  FRAM_ACCESS_CRC_BUSY, /* CRC hardware busy, transaction with FRAM could not take place */
89  FRAM_ACCESS_CRC_ERROR, /* Read CRC does not match with CRC computed on read data */
91 
92 /** configuration struct of database channel (data block) */
93 typedef struct {
94  void *blockptr;
95  uint32_t datalength;
96  uint32_t address;
98 
99 /** fram block identification numbers */
100 typedef enum {
108  FRAM_BLOCK_MAX, /**< DO NOT CHANGE, MUST BE THE LAST ENTRY */
110 
111 /**
112  * @brief Stores the version of the memory layout of the FRAM
113  * @details This struct stores with which memory-layout version the FRAM has
114  * been written. This allows the BMS to recognize an incompatible
115  * memory layout.
116  */
117 typedef struct {
118  FRAM_PROJECT_ID project; /*!< an identifier for the project, it is not
119  intended to migrate between different projects */
120  uint16_t version; /*!< version counter, i.e. for updating to a new version in the same project */
122 
123 /** struct for the FRAM entry of the SBC driver */
124 typedef struct {
125  uint8_t phase;
128 
129 /**
130  * state of charge (SOC). Since SOC is voltage dependent, three different
131  * values are used, min, max and average. SOC defined as a float number between
132  * 0.0f and 100.0f (0% and 100%)
133  */
134 typedef struct {
135  float minimumSoc_perc[BS_NR_OF_STRINGS]; /*!< minimum SOC */
136  float maximumSoc_perc[BS_NR_OF_STRINGS]; /*!< maximum SOC */
137  float averageSoc_perc[BS_NR_OF_STRINGS]; /*!< average SOC */
138 } FRAM_SOC_s;
139 
140 /**
141  * state of energy (SOE). Since SOE is voltage dependent, three different
142  * values are used, min, max and average. SOE defined as a float number between
143  * 0.0f and 100.0f (0% and 100%)
144  */
145 typedef struct {
146  float minimumSoe_perc[BS_NR_OF_STRINGS]; /*!< minimum SOE */
147  float maximumSoe_perc[BS_NR_OF_STRINGS]; /*!< maximum SOE */
148  float averageSoe_perc[BS_NR_OF_STRINGS]; /*!< average SOE */
149 } FRAM_SOE_s;
150 
151 /** flag to indicate if a deep-discharge in a string has been detected */
152 typedef struct {
153  bool deepDischargeFlag[BS_NR_OF_STRINGS]; /*!< false (0): no error, true (1): deep-discharge detected */
155 
156 /** flag to indicate if insulation ground error has been detected */
157 typedef struct {
158  bool groundErrorDetected; /*!< false (0): no error, true (1): gorund error detected */
160 
161 /**
162  * @brief struct that stores for each task the last violation of timing
163  */
164 typedef struct {
165  /** convenience flag that is set as long as any timing issues are recorded */
167  /** duration that has been recorded when the last violation of timings occurred */
169  /** timestamp that has been recorded when the violating execution of the task has been entered */
171  /** duration that has been recorded when the last violation of timings occurred */
173  /** timestamp that has been recorded when the violating execution of the task has been entered */
175  /** duration that has been recorded when the last violation of timings occurred */
177  /** timestamp that has been recorded when the violating execution of the task has been entered */
179  /** duration that has been recorded when the last violation of timings occurred */
181  /** timestamp that has been recorded when the violating execution of the task has been entered */
183  /** duration that has been recorded when the last violation of timings occurred */
185  /** timestamp that has been recorded when the violating execution of the task has been entered */
188 
189 /*========== Extern Constant and Variable Declarations ======================*/
190 
192 
193 /**
194  * Variables to be stored in FRAM
195  */
196 /**@{*/
198 extern FRAM_SOC_s fram_soc;
199 extern FRAM_SOE_s fram_soe;
204 /**@}*/
205 
206 /*========== Extern Function Prototypes =====================================*/
207 
208 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
209 
210 #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:85
@ FRAM_ACCESS_SPI_BUSY
Definition: fram_cfg.h:87
@ FRAM_ACCESS_CRC_BUSY
Definition: fram_cfg.h:88
@ FRAM_ACCESS_CRC_ERROR
Definition: fram_cfg.h:89
@ FRAM_ACCESS_OK
Definition: fram_cfg.h:86
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:79
FRAM_BLOCK_ID_e
Definition: fram_cfg.h:100
@ FRAM_BLOCK_ID_DEEP_DISCHARGE_FLAG
Definition: fram_cfg.h:104
@ FRAM_BLOCK_ID_VERSION
Definition: fram_cfg.h:101
@ FRAM_BLOCK_ID_SOC
Definition: fram_cfg.h:102
@ FRAM_BLOCK_ID_SBC_INIT_STATE
Definition: fram_cfg.h:103
@ FRAM_BLOCK_MAX
Definition: fram_cfg.h:108
@ FRAM_BLOCK_ID_SOE
Definition: fram_cfg.h:105
@ FRAM_BLOCK_ID_SYS_MON_RECORD
Definition: fram_cfg.h:106
@ FRAM_BLOCK_ID_INSULATION_FLAG
Definition: fram_cfg.h:107
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
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
General macros and definitions for the whole platform.
uint32_t address
Definition: fram_cfg.h:96
uint32_t datalength
Definition: fram_cfg.h:95
uint8_t phase
Definition: fram_cfg.h:125
STD_RETURN_TYPE_e finState
Definition: fram_cfg.h:126
struct that stores for each task the last violation of timing
Definition: fram_cfg.h:164
uint32_t taskEngineViolatingDuration
Definition: fram_cfg.h:168
uint32_t taskEngineEnterTimestamp
Definition: fram_cfg.h:170
uint32_t task10msViolatingDuration
Definition: fram_cfg.h:176
uint32_t task100msViolatingDuration
Definition: fram_cfg.h:180
uint32_t task100msEnterTimestamp
Definition: fram_cfg.h:182
uint32_t task1msViolatingDuration
Definition: fram_cfg.h:172
uint32_t task100msAlgorithmEnterTimestamp
Definition: fram_cfg.h:186
uint32_t task10msEnterTimestamp
Definition: fram_cfg.h:178
uint32_t task1msEnterTimestamp
Definition: fram_cfg.h:174
uint32_t task100msAlgorithmViolatingDuration
Definition: fram_cfg.h:184
Stores the version of the memory layout of the FRAM.
Definition: fram_cfg.h:117
FRAM_PROJECT_ID project
Definition: fram_cfg.h:118
uint16_t version
Definition: fram_cfg.h:120