foxBMS - Unit Tests  1.3.0
The foxBMS Unit Tests 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-05-30 (date of last update)
47  * @version v1.3.0
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 /** One channel for each contactor is required in this application */
86 #define SPS_NR_OF_REQUIRED_CONTACTOR_CHANNELS (BS_NR_OF_CONTACTORS)
87 
88 /** Calculate the number of available SPS channels */
89 #define SPS_NR_OF_AVAILABLE_SPS_CHANNELS (SPS_NR_CONTACTOR_PER_IC * SPS_NR_OF_IC)
90 
91 /* check if the number of contactors fits in the available channels */
92 #if (SPS_NR_OF_REQUIRED_CONTACTOR_CHANNELS > SPS_NR_OF_AVAILABLE_SPS_CHANNELS)
93 #error "Not enough contactor channels available for the required number of contactors."
94 #endif
95 
96 /** Defines the buffer size to communicate with the SPS IC.
97  *
98  * One 16 bit word per SPS IC so buffer size is equivalent to the number of
99  * SPS ICs.
100  *
101  * - 1 SPS IC -> Buffer size = 1
102  * - 2 SPS IC -> Buffer size = 2
103  * - 3 SPS IC -> Buffer size = 3
104  */
105 #define SPS_SPI_BUFFERSIZE SPS_NR_OF_IC
106 
107 /** Addresses of used control registers @{ */
108 #define SPS_GLOBAL_CONTROL_REGISTER_ADDRESS (0x00u)
109 #define SPS_OUTPUT_CONTROL_REGISTER_ADDRESS (0x02u)
110 #define SPS_C_CONTROL_REGISTER_ADDRESS (0x16u)
111 /**@}*/
112 /** Addresses of used diagnostic registers @{ */
113 #define SPS_OD_IOUT1_DIAG_REGISTER_ADDRESS (0x08u)
114 #define SPS_OD_IOUT2_DIAG_REGISTER_ADDRESS (0x09u)
115 #define SPS_OD_IOUT3_DIAG_REGISTER_ADDRESS (0x0Au)
116 #define SPS_OD_IOUT4_DIAG_REGISTER_ADDRESS (0x0Bu)
117 #define SPS_EN_IRQ_PIN_DIAG_REGISTER_ADDRESS (0x11u)
118 #define SPS_EN_WARN_PIN_DIAG_REGISTER_ADDRESS (0x13u)
119 /**@}*/
120 
121 /**
122  * These bits and positions are defined in
123  * figure 7 page 10 in data sheet Rev. 2 - 11 September 2019
124  */
125 /** This bit is set to 0 for a read register access, to 1 for a write register access */
126 #define SPS_RW_BIT_POSITION (15u)
127 /** Define for read register access */
128 #define SPS_RW_READ (0u)
129 /** Define for write register access */
130 #define SPS_RW_WRITE (1u)
131 /** In Tx SPI buffer, register address starts at bit 8 */
132 #define SPS_ADDRESS_BIT_START (8u)
133 /** This bit is set to 0 to read a diagnostic register, to 1 to read a control register */
134 #define SPS_DIAG_CTRL_BIT_POSITION (7u)
135 
136 /** value for the SPS normal mode */
137 #define SPS_NORMAL_MODE (0x01u)
138 /** value for the SPS strong drive */
139 #define SPS_STRONG_DRIVE (0x00u)
140 /** value for the SPS medium drive */
141 #define SPS_MEDIUM_DRIVE (0x01u)
142 /** bitshift for the mode bit in the SPS
143  *
144  * used for bitshifting #SPS_NORMAL_MODE to the right position
145  */
146 #define SPS_MODE_BIT_START (6u)
147 /** bitshift for the drive strength bit in the SPS */
148 #define SPS_DRIVE_STRENGTH_BIT_START (5u)
149 
150 /** LSB of current measurement of SPS channel in mA */
151 #define SPS_I_MEASUREMENT_LSB_mA (0.98f)
152 
153 /** current threshold that recognizes a contactor as closed */
154 #define SPS_CHANNEL_ON_DEFAULT_THRESHOLD_mA (20.0f)
155 
156 /** bitmask for reading the on-demand output current from a SPI transaction */
157 #define SPS_BITMASK_DIAGNOSTIC_ONDEMAND_OUTPUT_CURRENT (0x1FFFu)
158 
159 /** spi block identification numbers */
160 typedef enum {
165 
166 /** sps read types */
167 typedef enum {
168  SPS_READ_DIAGNOSTIC_REGISTER, /*!< diagnostic register read */
169  SPS_READ_CONTROL_REGISTER, /*!< control register read */
171 
172 /** functional state of a SPS channel */
173 typedef enum {
174  SPS_CHANNEL_OFF, /*!< sps channel is switched off */
175  SPS_CHANNEL_ON, /*!< sps channel is switched on */
177 
178 /** SPS channel state */
179 typedef struct {
180  SPS_CHANNEL_FUNCTION_e channelRequested; /*!< requested state of the channel */
181  SPS_CHANNEL_FUNCTION_e channel; /*!< state of the channel */
182  float current_mA; /*!< current flow in this channel in mA */
184  affiliation; /*!< affiliation of the channel (if it is contactor or something else) */
185  const float thresholdFeedbackOn_mA; /*!< current threshold in mA above which the channel is considered "on" */
187 
188 /** SPS channel mapping to feedback pin */
189 typedef struct {
190  const uint8_t pexDevice; /*!< port expander number */
191  const uint8_t pexChannel; /*!< pin number on the addresses port expander */
193 
194 /*================== Main precharge configuration ====================*/
195 
196 /*========== Extern Constant and Variable Declarations ======================*/
197 
198 /** State for the CONT handling */
199 typedef enum {
210 } SPS_STATE_e;
211 
212 /** Actions to do for the Smart Power Switch IC */
213 typedef enum {
221 } SPS_ACTION_e;
222 
224 
226 
227 /*========== Extern Function Prototypes =====================================*/
228 
229 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
230 
231 #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:89
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:167
@ SPS_READ_DIAGNOSTIC_REGISTER
Definition: sps_cfg.h:168
@ SPS_READ_CONTROL_REGISTER
Definition: sps_cfg.h:169
SPS_ACTION_e
Definition: sps_cfg.h:213
@ SPS_ACTION_READ_CURRENT_MEASUREMENT2
Definition: sps_cfg.h:217
@ SPS_ACTION_READ_CURRENT_MEASUREMENT1
Definition: sps_cfg.h:216
@ SPS_ACTION_TRIGGER_CURRENT_MEASUREMENT
Definition: sps_cfg.h:215
@ SPS_ACTION_READ_EN_IRQ_PIN
Definition: sps_cfg.h:220
@ SPS_ACTION_READ_CURRENT_MEASUREMENT4
Definition: sps_cfg.h:219
@ SPS_ACTION_CONFIGURE_CONTROL_REGISTER
Definition: sps_cfg.h:214
@ SPS_ACTION_READ_CURRENT_MEASUREMENT3
Definition: sps_cfg.h:218
SPS_CHANNEL_FUNCTION_e
Definition: sps_cfg.h:173
@ SPS_CHANNEL_ON
Definition: sps_cfg.h:175
@ SPS_CHANNEL_OFF
Definition: sps_cfg.h:174
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:160
@ SPS_andWithCurrentValue
Definition: sps_cfg.h:163
@ SPS_orWithCurrentValue
Definition: sps_cfg.h:162
@ SPS_replaceCurrentValue
Definition: sps_cfg.h:161
SPS_STATE_e
Definition: sps_cfg.h:199
@ SPS_TRIGGER_CURRENT_MEASUREMENT
Definition: sps_cfg.h:204
@ SPS_CONFIGURE_CONTROL_REGISTER
Definition: sps_cfg.h:203
@ SPS_READ_MEASURED_CURRENT2
Definition: sps_cfg.h:206
@ SPS_READ_MEASURED_CURRENT1
Definition: sps_cfg.h:205
@ SPS_RESET_LOW
Definition: sps_cfg.h:201
@ SPS_READ_EN_IRQ_PIN
Definition: sps_cfg.h:209
@ SPS_READ_MEASURED_CURRENT3
Definition: sps_cfg.h:207
@ SPS_START
Definition: sps_cfg.h:200
@ SPS_READ_MEASURED_CURRENT4
Definition: sps_cfg.h:208
@ SPS_RESET_HIGH
Definition: sps_cfg.h:202
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:180
SPS_CHANNEL_FUNCTION_e channel
Definition: sps_cfg.h:181
const float thresholdFeedbackOn_mA
Definition: sps_cfg.h:185
const SPS_CHANNEL_AFFILIATION_e affiliation
Definition: sps_cfg.h:184