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