foxBMS - Unit Tests  1.1.2
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 2020-10-14 (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_GIOPORT (hetREG2->DOUT)
68 #define SPS_RESET_GIOPORT_DIR (hetREG2->DIR)
69 #define SPS_RESET_PIN (16u)
70 /**@}*/
71 
72 /** Each SPS IC has four outputs */
73 #define SPS_NR_CONTACTOR_PER_IC (4u)
74 
75 /** Number of SPS IC that are populated on the hardware (in daisy-chain) */
76 #define SPS_NR_OF_IC (3u)
77 
78 /** One channel for each contactor is required in this application */
79 #define SPS_NR_OF_REQUIRED_CONTACTOR_CHANNELS (BS_NR_OF_CONTACTORS)
80 
81 /** Calculate the number of available SPS channels */
82 #define SPS_NR_OF_AVAILABLE_SPS_CHANNELS (SPS_NR_CONTACTOR_PER_IC * SPS_NR_OF_IC)
83 
84 /* check if the number of contactors fits in the available channels */
85 #if (SPS_NR_OF_REQUIRED_CONTACTOR_CHANNELS > SPS_NR_OF_AVAILABLE_SPS_CHANNELS)
86 #error "Not enough contactor channels available for the required number of contactors."
87 #endif
88 
89 /** Defines the buffer size to communicate with the SPS IC.
90  *
91  * One 16 bit word per SPS IC so buffer size is equivalent to the number of
92  * SPS ICs.
93  *
94  * - 1 SPS IC -> Buffer size = 1
95  * - 2 SPS IC -> Buffer size = 2
96  * - 3 SPS IC -> Buffer size = 3
97  */
98 #define SPS_SPI_BUFFERSIZE SPS_NR_OF_IC
99 
100 /** Addresses of used control registers @{ */
101 #define SPS_GLOBAL_CONTROL_REGISTER_ADDRESS (0x00u)
102 #define SPS_OUTPUT_CONTROL_REGISTER_ADDRESS (0x02u)
103 #define SPS_C_CONTROL_REGISTER_ADDRESS (0x16u)
104 /**@}*/
105 /** Addresses of used diagnostic registers @{ */
106 #define SPS_OD_IOUT1_DIAG_REGISTER_ADDRESS (0x08u)
107 #define SPS_OD_IOUT2_DIAG_REGISTER_ADDRESS (0x09u)
108 #define SPS_OD_IOUT3_DIAG_REGISTER_ADDRESS (0x0Au)
109 #define SPS_OD_IOUT4_DIAG_REGISTER_ADDRESS (0x0Bu)
110 #define SPS_EN_IRQ_PIN_DIAG_REGISTER_ADDRESS (0x11u)
111 #define SPS_EN_WARN_PIN_DIAG_REGISTER_ADDRESS (0x13u)
112 /**@}*/
113 
114 /**
115  * These bits and positions are defined in
116  * figure 7 page 10 in datasheet Rev. 2 - 11 September 2019
117  */
118 /** This bit is set to 0 for a read register access, to 1 for a write register access */
119 #define SPS_RW_BIT_POSITION (15u)
120 /** Define for read register access */
121 #define SPS_RW_READ (0u)
122 /** Define for write register access */
123 #define SPS_RW_WRITE (1u)
124 /** In Tx SPI buffer, register address starts at bit 8 */
125 #define SPS_ADDRESS_BIT_START (8u)
126 /** This bit is set to 0 to read a diagnostic register, to 1 to read a control register */
127 #define SPS_DIAG_CTRL_BIT_POSITION (7u)
128 
129 /** value for the SPS normal mode */
130 #define SPS_NORMAL_MODE (0x01u)
131 /** value for the SPS strong drive */
132 #define SPS_STRONG_DRIVE (0x00u)
133 /** value for the SPS medium drive */
134 #define SPS_MEDIUM_DRIVE (0x01u)
135 /** bitshift for the mode bit in the SPS
136  *
137  * used for bitshifting #SPS_NORMAL_MODE to the right position
138  */
139 #define SPS_MODE_BIT_START (6u)
140 /** bitshift for the drive strength bit in the SPS */
141 #define SPS_DRIVE_STRENGTH_BIT_START (5u)
142 
143 /** LSB of current measurement of SPS channel in mA */
144 #define SPS_I_MEASUREMENT_LSB_mA (0.98f)
145 
146 /** current threshold that recognizes a contactor as closed */
147 #define SPS_CHANNEL_ON_DEFAULT_THRESHOLD_mA (20.0f)
148 
149 /** bitmask for reading the on-demand output current from a SPI transaction */
150 #define SPS_BITMASK_DIAGNOSTIC_ONDEMAND_OUTPUT_CURRENT (0x1FFFu)
151 
152 /** spi block identification numbers */
153 typedef enum SPS_WRITE_TYPE {
158 
159 /** sps read types */
160 typedef enum SPS_READ_TYPE {
161  SPS_READ_DIAGNOSTIC_REGISTER, /*!< diagnostic register read */
162  SPS_READ_CONTROL_REGISTER, /*!< control register read */
164 
165 /** functional state of a SPS channel */
166 typedef enum SPS_CHANNEL_FUNCTION {
167  SPS_CHANNEL_OFF, /*!< sps channel is switched off */
168  SPS_CHANNEL_ON, /*!< sps channel is switched on */
170 
171 /** SPS channel state */
172 typedef struct SPS_CHANNEL_STATE {
173  SPS_CHANNEL_FUNCTION_e channelRequested; /*!< requested state of the channel */
174  SPS_CHANNEL_FUNCTION_e channel; /*!< state of the channel */
175  float current_mA; /*!< current flow in this channel in mA */
177  affiliation; /*!< affiliation of the channel (if it is contactor or something else) */
178  const float thresholdFeedbackOn_mA; /*!< current threshold in mA above which the channel is considered "on" */
180 
181 /*================== Main precharge configuration ====================*/
182 
183 /*========== Extern Constant and Variable Declarations ======================*/
184 
185 /** State for the CONT handling */
186 typedef enum SPS_STATE {
198 
199 /** Actions to do for the Smart Power Switch IC */
200 typedef enum SPS_ACTION {
209 
211 
212 /*========== Extern Function Prototypes =====================================*/
213 
214 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
215 
216 #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:82
SPS_CHANNEL_FUNCTION
Definition: sps_cfg.h:166
@ SPS_CHANNEL_ON
Definition: sps_cfg.h:168
@ SPS_CHANNEL_OFF
Definition: sps_cfg.h:167
SPS_STATE
Definition: sps_cfg.h:186
@ SPS_TRIGGER_CURRENT_MEASUREMENT
Definition: sps_cfg.h:191
@ SPS_CONFIGURE_CONTROL_REGISTER
Definition: sps_cfg.h:190
@ SPS_READ_MEASURED_CURRENT2
Definition: sps_cfg.h:193
@ SPS_READ_MEASURED_CURRENT1
Definition: sps_cfg.h:192
@ SPS_RESET_LOW
Definition: sps_cfg.h:188
@ SPS_READ_EN_IRQ_PIN
Definition: sps_cfg.h:196
@ SPS_READ_MEASURED_CURRENT3
Definition: sps_cfg.h:194
@ SPS_START
Definition: sps_cfg.h:187
@ SPS_READ_MEASURED_CURRENT4
Definition: sps_cfg.h:195
@ SPS_RESET_HIGH
Definition: sps_cfg.h:189
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:63
enum SPS_STATE SPS_STATE_e
SPS_WRITE_TYPE
Definition: sps_cfg.h:153
@ SPS_andWithCurrentValue
Definition: sps_cfg.h:156
@ SPS_orWithCurrentValue
Definition: sps_cfg.h:155
@ SPS_replaceCurrentValue
Definition: sps_cfg.h:154
SPS_READ_TYPE
Definition: sps_cfg.h:160
@ SPS_READ_DIAGNOSTIC_REGISTER
Definition: sps_cfg.h:161
@ SPS_READ_CONTROL_REGISTER
Definition: sps_cfg.h:162
enum SPS_CHANNEL_FUNCTION SPS_CHANNEL_FUNCTION_e
enum SPS_READ_TYPE SPS_READ_TYPE_e
SPS_ACTION
Definition: sps_cfg.h:200
@ SPS_ACTION_READ_CURRENT_MEASUREMENT2
Definition: sps_cfg.h:204
@ SPS_ACTION_READ_CURRENT_MEASUREMENT1
Definition: sps_cfg.h:203
@ SPS_ACTION_TRIGGER_CURRENT_MEASUREMENT
Definition: sps_cfg.h:202
@ SPS_ACTION_READ_EN_IRQ_PIN
Definition: sps_cfg.h:207
@ SPS_ACTION_READ_CURRENT_MEASUREMENT4
Definition: sps_cfg.h:206
@ SPS_ACTION_CONFIGURE_CONTROL_REGISTER
Definition: sps_cfg.h:201
@ SPS_ACTION_READ_CURRENT_MEASUREMENT3
Definition: sps_cfg.h:205
Types for the SPS driver.
enum SPS_CHANNEL_AFFILIATION SPS_CHANNEL_AFFILIATION_e
affiliation type of a sps channel
const float thresholdFeedbackOn_mA
Definition: sps_cfg.h:178
SPS_CHANNEL_FUNCTION_e channelRequested
Definition: sps_cfg.h:173
const SPS_CHANNEL_AFFILIATION_e affiliation
Definition: sps_cfg.h:177
float current_mA
Definition: sps_cfg.h:175
SPS_CHANNEL_FUNCTION_e channel
Definition: sps_cfg.h:174