foxBMS  1.4.1
The foxBMS Battery Management System API Documentation
sps_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 sps_cfg.h
44  * @author foxBMS Team
45  * @date 2020-10-14 (date of creation)
46  * @updated 2022-10-27 (date of last update)
47  * @version v1.4.1
48  * @ingroup DRIVERS_CONF
49  * @prefix SPS
50  *
51  * @brief Header for the configuration for the driver for the smart power switches
52  *
53  */
54 
55 #ifndef FOXBMS__SPS_CFG_H_
56 #define FOXBMS__SPS_CFG_H_
57 
58 /*========== Includes =======================================================*/
59 #include "general.h"
60 
61 #include "battery_system_cfg.h"
62 
63 #include "sps_types.h"
64 
65 /*========== Macros and Definitions =========================================*/
66 
67 /** GIO defines for pin to drive reset line of SPS @{ */
68 #define SPS_RESET_GIO_PORT (hetREG2->DOUT)
69 #define SPS_RESET_GIO_PORT_DIR (hetREG2->DIR)
70 #define SPS_RESET_PIN (16u)
71 /**@}*/
72 
73 /** GIO defines for pin to drive feedback enable MOSFET of SPS @{ */
74 #define SPS_FEEDBACK_GIO_PORT (hetREG2->DOUT)
75 #define SPS_FEEDBACK_GIO_PORT_DIR (hetREG2->DIR)
76 #define SPS_FEEDBACK_PIN (9u)
77 /**@}*/
78 
79 /** Each SPS IC has four outputs */
80 #define SPS_NR_CONTACTOR_PER_IC (4u)
81 
82 /** Number of SPS IC that are populated on the hardware (in daisy-chain) */
83 #define SPS_NR_OF_IC (2u)
84 
85 /** Defines for the individual SPS channels @{ */
86 #define SPS_CHANNEL_0 ((SPS_CHANNEL_INDEX)0)
87 #define SPS_CHANNEL_1 ((SPS_CHANNEL_INDEX)1)
88 #define SPS_CHANNEL_2 ((SPS_CHANNEL_INDEX)2)
89 #define SPS_CHANNEL_3 ((SPS_CHANNEL_INDEX)3)
90 #define SPS_CHANNEL_4 ((SPS_CHANNEL_INDEX)4)
91 #define SPS_CHANNEL_5 ((SPS_CHANNEL_INDEX)5)
92 #define SPS_CHANNEL_6 ((SPS_CHANNEL_INDEX)6)
93 #define SPS_CHANNEL_7 ((SPS_CHANNEL_INDEX)7)
94 /**@}*/
95 
96 /** One channel for each contactor is required in this application */
97 #define SPS_NR_OF_REQUIRED_CONTACTOR_CHANNELS (BS_NR_OF_CONTACTORS)
98 
99 /** Calculate the number of available SPS channels */
100 #define SPS_NR_OF_AVAILABLE_SPS_CHANNELS (SPS_NR_CONTACTOR_PER_IC * SPS_NR_OF_IC)
101 
102 /* check if the number of contactors fits in the available channels */
103 #if (SPS_NR_OF_REQUIRED_CONTACTOR_CHANNELS > SPS_NR_OF_AVAILABLE_SPS_CHANNELS)
104 #error "Not enough contactor channels available for the required number of contactors."
105 #endif
106 
107 /** Defines the buffer size to communicate with the SPS IC.
108  *
109  * One 16 bit word per SPS IC so buffer size is equivalent to the number of
110  * SPS ICs.
111  *
112  * - 1 SPS IC -> Buffer size = 1
113  * - 2 SPS IC -> Buffer size = 2
114  * - 3 SPS IC -> Buffer size = 3
115  */
116 #define SPS_SPI_BUFFERSIZE SPS_NR_OF_IC
117 
118 /** Addresses of used control registers @{ */
119 #define SPS_GLOBAL_CONTROL_REGISTER_ADDRESS (0x00u)
120 #define SPS_OUTPUT_CONTROL_REGISTER_ADDRESS (0x02u)
121 #define SPS_C_CONTROL_REGISTER_ADDRESS (0x16u)
122 /**@}*/
123 /** Addresses of used diagnostic registers @{ */
124 #define SPS_ISR_IRQ_DIAG_REGISTER_ADDRESS (0x06u)
125 #define SPS_ISR_WARN_DIAG_REGISTER_ADDRESS (0x07u)
126 #define SPS_OD_IOUT1_DIAG_REGISTER_ADDRESS (0x08u)
127 #define SPS_OD_IOUT2_DIAG_REGISTER_ADDRESS (0x09u)
128 #define SPS_OD_IOUT3_DIAG_REGISTER_ADDRESS (0x0Au)
129 #define SPS_OD_IOUT4_DIAG_REGISTER_ADDRESS (0x0Bu)
130 /**@}*/
131 
132 /**
133  * These bits and positions are defined in
134  * figure 7 page 10 in data sheet Rev. 2 - 11 September 2019
135  */
136 /** This bit is set to 0 for a read register access, to 1 for a write register access */
137 #define SPS_RW_BIT_POSITION (15u)
138 /** Define for read register access */
139 #define SPS_RW_READ (0u)
140 /** Define for write register access */
141 #define SPS_RW_WRITE (1u)
142 /** In Tx SPI buffer, register address starts at bit 8 */
143 #define SPS_ADDRESS_BIT_START (8u)
144 /** This bit is set to 0 to read a diagnostic register, to 1 to read a control register */
145 #define SPS_DIAG_CTRL_BIT_POSITION (7u)
146 
147 /** value for the SPS normal mode */
148 #define SPS_NORMAL_MODE (0x01u)
149 /** value for the SPS strong drive */
150 #define SPS_STRONG_DRIVE (0x00u)
151 /** value for the SPS medium drive */
152 #define SPS_MEDIUM_DRIVE (0x01u)
153 /** bitshift for the mode bit in the SPS
154  *
155  * used for bitshifting #SPS_NORMAL_MODE to the right position
156  */
157 #define SPS_MODE_BIT_START (6u)
158 /** bitshift for the drive strength bit in the SPS */
159 #define SPS_DRIVE_STRENGTH_BIT_START (5u)
160 
161 /** LSB of current measurement of SPS channel in mA */
162 #define SPS_I_MEASUREMENT_LSB_mA (0.98f)
163 
164 /** current threshold that recognizes a contactor as closed */
165 #define SPS_CHANNEL_ON_DEFAULT_THRESHOLD_mA (20.0f)
166 
167 /** bitmask for reading the on-demand output current from a SPI transaction */
168 #define SPS_BITMASK_DIAGNOSTIC_ONDEMAND_OUTPUT_CURRENT (0x1FFFu)
169 
170 /** spi block identification numbers */
171 typedef enum {
176 
177 /** sps read types */
178 typedef enum {
179  SPS_READ_DIAGNOSTIC_REGISTER, /*!< diagnostic register read */
180  SPS_READ_CONTROL_REGISTER, /*!< control register read */
182 
183 /** functional state of a SPS channel */
184 typedef enum {
185  SPS_CHANNEL_OFF, /*!< sps channel is switched off */
186  SPS_CHANNEL_ON, /*!< sps channel is switched on */
188 
189 /** SPS channel state */
190 typedef struct {
191  SPS_CHANNEL_FUNCTION_e channelRequested; /*!< requested state of the channel */
192  SPS_CHANNEL_FUNCTION_e channel; /*!< state of the channel */
193  float current_mA; /*!< current flow in this channel in mA */
195  affiliation; /*!< affiliation of the channel (if it is contactor or something else) */
196  const float thresholdFeedbackOn_mA; /*!< current threshold in mA above which the channel is considered "on" */
198 
199 /** SPS channel mapping to feedback pin */
200 typedef struct {
201  const uint8_t pexDevice; /*!< port expander number */
202  const uint8_t pexChannel; /*!< pin number on the addresses port expander */
204 
205 /*================== Main precharge configuration ====================*/
206 
207 /*========== Extern Constant and Variable Declarations ======================*/
208 
209 /** State for the CONT handling */
210 typedef enum {
221 } SPS_STATE_e;
222 
223 /** Actions to do for the Smart Power Switch IC */
224 typedef enum {
232 } SPS_ACTION_e;
233 
235 
237 
238 /*========== Extern Function Prototypes =====================================*/
239 
240 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
241 
242 #endif /* FOXBMS__SPS_CFG_H_ */
Configuration of the battery system (e.g., number of battery modules, battery cells,...
General macros and definitions for the whole platform.
#define SPS_NR_OF_AVAILABLE_SPS_CHANNELS
Definition: sps_cfg.h:100
SPS_CHANNEL_STATE_s sps_channelStatus[SPS_NR_OF_AVAILABLE_SPS_CHANNELS]
Definition: sps_cfg.c:66
SPS_READ_TYPE_e
Definition: sps_cfg.h:178
@ SPS_READ_DIAGNOSTIC_REGISTER
Definition: sps_cfg.h:179
@ SPS_READ_CONTROL_REGISTER
Definition: sps_cfg.h:180
SPS_ACTION_e
Definition: sps_cfg.h:224
@ SPS_ACTION_READ_CURRENT_MEASUREMENT2
Definition: sps_cfg.h:228
@ SPS_ACTION_READ_CURRENT_MEASUREMENT1
Definition: sps_cfg.h:227
@ SPS_ACTION_TRIGGER_CURRENT_MEASUREMENT
Definition: sps_cfg.h:226
@ SPS_ACTION_READ_EN_IRQ_PIN
Definition: sps_cfg.h:231
@ SPS_ACTION_READ_CURRENT_MEASUREMENT4
Definition: sps_cfg.h:230
@ SPS_ACTION_CONFIGURE_CONTROL_REGISTER
Definition: sps_cfg.h:225
@ SPS_ACTION_READ_CURRENT_MEASUREMENT3
Definition: sps_cfg.h:229
SPS_CHANNEL_FUNCTION_e
Definition: sps_cfg.h:184
@ SPS_CHANNEL_ON
Definition: sps_cfg.h:186
@ SPS_CHANNEL_OFF
Definition: sps_cfg.h:185
const SPS_CHANNEL_FEEDBACK_MAPPING_s sps_kChannelFeedbackMapping[SPS_NR_OF_AVAILABLE_SPS_CHANNELS]
Definition: sps_cfg.c:83
SPS_WRITE_TYPE_e
Definition: sps_cfg.h:171
@ SPS_andWithCurrentValue
Definition: sps_cfg.h:174
@ SPS_orWithCurrentValue
Definition: sps_cfg.h:173
@ SPS_replaceCurrentValue
Definition: sps_cfg.h:172
SPS_STATE_e
Definition: sps_cfg.h:210
@ SPS_TRIGGER_CURRENT_MEASUREMENT
Definition: sps_cfg.h:215
@ SPS_CONFIGURE_CONTROL_REGISTER
Definition: sps_cfg.h:214
@ SPS_READ_MEASURED_CURRENT2
Definition: sps_cfg.h:217
@ SPS_READ_MEASURED_CURRENT1
Definition: sps_cfg.h:216
@ SPS_RESET_LOW
Definition: sps_cfg.h:212
@ SPS_READ_EN_IRQ_PIN
Definition: sps_cfg.h:220
@ SPS_READ_MEASURED_CURRENT3
Definition: sps_cfg.h:218
@ SPS_START
Definition: sps_cfg.h:211
@ SPS_READ_MEASURED_CURRENT4
Definition: sps_cfg.h:219
@ SPS_RESET_HIGH
Definition: sps_cfg.h:213
Types for the SPS driver.
SPS_CHANNEL_AFFILIATION_e
affiliation type of a sps channel
Definition: sps_types.h:72
SPS_CHANNEL_FUNCTION_e channelRequested
Definition: sps_cfg.h:191
SPS_CHANNEL_FUNCTION_e channel
Definition: sps_cfg.h:192
const float thresholdFeedbackOn_mA
Definition: sps_cfg.h:196
const SPS_CHANNEL_AFFILIATION_e affiliation
Definition: sps_cfg.h:195