foxBMS-UnitTests  1.0.0
The foxBMS Unit Tests API Documentation
ltc_6806_cfg.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der
4  * angewandten Forschung e.V. All rights reserved.
5  *
6  * BSD 3-Clause License
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  * 1. Redistributions of source code must retain the above copyright notice,
10  * this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * 3. Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28  * POSSIBILITY OF SUCH DAMAGE.
29  *
30  * We kindly request you to use one or more of the following phrases to refer
31  * to foxBMS in your hardware, software, documentation or advertising
32  * materials:
33  *
34  * ″This product uses parts of foxBMS®″
35  *
36  * ″This product includes parts of foxBMS®″
37  *
38  * ″This product is derived from foxBMS®″
39  *
40  */
41 
42 /**
43  * @file ltc_6806_cfg.h
44  * @author foxBMS Team
45  * @date 2015-02-18 (date of creation)
46  * @updated 2021-03-24 (date of last update)
47  * @ingroup DRIVERS_CONFIGURATION
48  * @prefix LTC
49  *
50  * @brief Header for the configuration for the LTC 6806 monitoring IC
51  *
52  */
53 
54 #ifndef FOXBMS__LTC_6806_CFG_H_
55 #define FOXBMS__LTC_6806_CFG_H_
56 
57 /*========== Includes =======================================================*/
58 /* clang-format off */
59 #include "ltc_cfg.h"
60 /* clang-format on */
61 
62 #include "ltc_defs.h"
63 #include "battery_system_cfg.h"
64 
65 #include "ltc_mic_dma.h"
66 #include "spi.h"
67 
68 /*========== Macros and Definitions =========================================*/
69 /**
70  * @ingroup CONFIG_LTC
71  * If set to 1 LTC driver is configured to use foxBMS slave boards version 1.x
72  * If set to 2 LTC driver is configured to use foxBMS slave boards version 2.x
73  */
74 #define SLAVE_BOARD_VERSION (2)
75 
76 /**
77  * If set to 0 LTC driver is configured to use PCA8574 port expander
78  * If set to 1 LTC driver is configured to use TCA6408A port expander
79  */
80 #define LTC_PORTEXPANDER_VERSION (1)
81 
82 /**
83  * Address of TI port expander (0 or 1)
84  */
85 #define LTC_PORTEXPANDER_ADR_TI (0)
86 
87 /** Controls if PEC should be discarded (true) or not (false) */
88 #define LTC_DISCARD_PEC (false)
89 
90 /** Number of multiplexer used per LTC-IC */
91 #define LTC_N_MUX_PER_LTC (3)
92 
93 /** Number of channels per multiplexer */
94 #define LTC_N_MUX_CHANNELS_PER_MUX (8)
95 
96 /** Number of multiplexer measurements per LTC cycle */
97 #define LTC_NUMBER_OF_MUX_MEASUREMENTS_PER_CYCLE (8)
98 
99 /** Number of multiplexed channels per LTC-IC */
100 #define LTC_N_MUX_CHANNELS_PER_LTC (LTC_N_MUX_PER_LTC * LTC_N_MUX_CHANNELS_PER_MUX)
101 
102 /** Number of LTC-ICs per battery module */
103 #define LTC_NUMBER_OF_LTC_PER_MODULE (1u)
104 
105 /**
106  * Voltage measurement range for fuel cells
107  * LSB = 1.5 mV if HIRNG = 0u
108  * LSB = 3.0 mV if HIRNG = 1u
109  */
110 #define LTC_HIRNG (0u)
111 
112 /** Open-wire voltage measurement time for fuel cells */
113 #define LTC_FUEL_CELL_ADOW_TIME_MS (100U + 1U)
114 
115 /** Open-wire detection threshold */
116 #define LTC_ADOW_THRESHOLD (-200)
117 
118 /**
119  * Measurement modus for voltages, possible values:
120  * - LTC_ADCMODE_NORMAL_DCP0
121  * - LTC_ADCMODE_FILTERED_DCP0
122  * - LTC_ADCMODE_FAST_DCP0
123  */
124 #define LTC_VOLTAGE_MEASUREMENT_MODE (LTC_ADCMODE_NORMAL_DCP0)
125 
126 /**
127  * Measurement modus for GPIOs, possible values:
128  * - LTC_ADCMODE_NORMAL_DCP0
129  * - LTC_ADCMODE_FILTERED_DCP0
130  * - LTC_ADCMODE_FAST_DCP0
131  */
132 #define LTC_GPIO_MEASUREMENT_MODE (LTC_ADCMODE_NORMAL_DCP0)
133 
134 /**
135  * Measurement modus for Open-wire check, possible values:
136  * - LTC_ADCMODE_NORMAL_DCP0
137  * - LTC_ADCMODE_FILTERED_DCP0
138  */
139 #define LTC_OW_MEASUREMENT_MODE (LTC_ADCMODE_NORMAL_DCP0)
140 
141 /**
142  * Timeout in milliseconds added to the transmission time for interrupt-based
143  * SPI transmission.
144  */
145 #define LTC_TRANSMISSION_TIMEOUT (10)
146 
147 /**
148  * SPI1 is used for communication with LTC
149  * @{
150  */
151 #define LTC_SPI_HANDLE &spi_devices[0]
152 #define LTC_SPI_INSTANCE *LTC_SPI_HANDLE.Instance
153 #define LTC_SPI_PRESCALER *LTC_SPI_HANDLE.Init.BaudRatePrescaler
154 /**@}*/
155 
156 /** start definition of LTC timings; Twake (see LTC datasheet) */
157 #define LTC_TWAKE_US (300)
158 /** start definition of LTC timings; Tready (see LTC datasheet) */
159 #define LTC_TREADY_US (10)
160 /** start definition of LTC timings; Tidle (see LTC datasheet) */
161 #define LTC_TIDLE_US (6700)
162 
163 /** LTC SPI wakeup time */
164 #define LTC_SPI_WAKEUP_WAIT_TIME_US (30U)
165 
166 /** Time to measure all fuel cells in normal mode 10280 µs */
167 #define LTC_FUELCELL_NORMAL_ALL_CELLS_MS (11)
168 
169 /** LTC statemachine short time definition in ms */
170 #define LTC_STATEMACH_SHORTTIME (1)
171 
172 /**
173  * time for the first initialization of the daisy chain
174  * see LTC6804 datasheet page 41
175  */
176 #define LTC_STATEMACH_DAISY_CHAIN_FIRST_INITIALIZATION_TIME ((LTC_TWAKE_US * LTC_N_LTC) / 1000)
177 /**
178  * time for the second initialization of the daisy chain
179  * see LTC6804 datasheet page 41
180  */
181 #define LTC_STATEMACH_DAISY_CHAIN_SECOND_INITIALIZATION_TIME ((LTC_TREADY_US * LTC_N_LTC) / 1000)
182 
183 /*
184  * Timings of Voltage Cell and GPIO measurement for all cells or all GPIO
185  */
186 
187 /**
188  * ~1.1ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
189  * unit: ms
190  */
191 #define LTC_STATEMACH_MEAS_ALL_FAST_TCYCLE (2)
192 
193 /**
194  * ~2.3ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
195  * unit: ms
196  */
197 #define LTC_STATEMACH_MEAS_ALL_NORMAL_TCYCLE (3)
198 
199 /**
200  * ~201ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
201  * unit: ms
202  */
203 #define LTC_STATEMACH_MEAS_ALL_FILTERED_TCYCLE (202)
204 
205 /*
206  * Timings of Voltage Cell and GPIO measurement for a pair of cells or a single GPIO
207  */
208 
209 /**
210  * ~0.201ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
211  * unit: ms
212  */
213 #define LTC_STATEMACH_MEAS_SINGLE_FAST_TCYCLE (1)
214 
215 /**
216  * ~0.405ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
217  * unit: ms
218  */
219 #define LTC_STATEMACH_MEAS_SINGLE_NORMAL_TCYCLE (1)
220 
221 /**
222  * ~34 ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
223  * unit: ms
224  */
225 #define LTC_STATEMACH_MEAS_SINGLE_FILTERED_TCYCLE (35)
226 
227 /** LTC statemachine sequence error timing in ms */
228 #define LTC_STATEMACH_SEQERRTTIME (5)
229 /** LTC statemachine CRC-transmission error timing in ms */
230 #define LTC_STATEMACH_PECERRTIME (1)
231 
232 /**
233  * Maximum number of re-tries in case of CRC error during the communication with daisy chain
234  * before going into error state
235  */
236 #define LTC_TRANSMIT_PECERRLIMIT (10)
237 
238 /**
239  * Maximum number of re-tries in case of SPI error during the communication with daisy chain
240  * before going into error state
241  */
242 #define LTC_TRANSMIT_SPIERRLIMIT (3)
243 
244 /** If set to 1, check if multiplexers acknowledged transmission */
245 #define LTC_READCOM (0)
246 
247 /**
248  * ------------------- OPEN WIRE CHECK ------------------------
249  * If open-wire check is performed cell voltages and temperatures are not
250  * updated and thus old values can be transmitted on the CAN bus. Check time
251  * is dependent on module configuration and external capacitance. Activate
252  * open-wire check with care! See table below for various measured open-wire
253  * check durations! (set to true or false)
254  */
255 #define LTC_STANDBY_PERIODIC_OPEN_WIRE_CHECK (false)
256 
257 /** Periodic open-wire check time in STANDBY state in ms */
258 #define LTC_STANDBY_OPEN_WIRE_PERIOD_ms (600000)
259 
260 /** open-wire check in normal mode (set to true or false) */
261 #define LTC_NORMAL_PERIODIC_OPEN_WIRE_CHECK (false)
262 
263 /** Periodic open-wire check time in NORMAL state in ms */
264 #define LTC_NORMAL_OPEN_WIRE_PERIOD_ms (600000)
265 
266 /** open-wire check in charge mode (set to true or false) */
267 #define LTC_CHARGE_PERIODIC_OPEN_WIRE_CHECK (false)
268 
269 /** Periodic open-wire check time in CHARGE state in ms */
270 #define LTC_CHARGE_OPEN_WIRE_PERIOD_ms (600000)
271 
272 /** Periodic open-wire check time in ERROR state in ms */
273 #define LTC_ERROR_OPEN_WIRE_PERIOD_ms (30000)
274 
275 /**
276  * Number of required ADOW commands because of external C-Pin capacitance and
277  * the respective duration to perform an open wire check for 14 modules with
278  * 12 cells each. During this time no cell voltages and temperatures are measured!
279  * +----------------+--------------+---------------+----------+----------+
280  * | External C pin | Normal mode | Filtered mode | Duration | Duration |
281  * | capacitance | | | normal | filtered |
282  * | ---------------+--------------+---------------+----------+----------+
283  * | <= 10nF | 2 | 2 | 32ms | 828ms |
284  * | 100nF | 10 | 2 | 112ms | 828ms |
285  * | 1uF | 100 | 2 | 1012ms | 828ms |
286  * | C | 1.5+(C/10nF) | 2 | | |
287  * +----------------+--------------+---------------+----------+----------+
288  */
289 #define LTC_NMBR_REQ_ADOW_COMMANDS (2)
290 
291 /**
292  * Transmit functions
293  * @{
294  */
295 #define LTC_TransmitWakeUp(spi_ltcInterface) SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US)
296 #define LTC_TransmitI2cCommand(spi_ltcInterface, txbuf) \
297  SPI_TransmitDataWithDummy(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US, txbuf, 4 + 9)
298 #define LTC_TransmitCommand(spi_ltcInterface, command) \
299  SPI_TransmitDataWithDummy(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US, command, 4)
300 #define LTC_TransmitReceiveData(spi_ltcInterface, txbuf, rxbuf, length) \
301  SPI_TransmitReceiveDataWithDummyDma(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US, txbuf, rxbuf, length)
302 /**@}*/
303 
304 /*========== Extern Constant and Variable Declarations ======================*/
305 
306 /**
307  * On the foxBMS slave board there are 6 multiplexer inputs dedicated to temperature
308  * sensors by default.
309  * Lookup table between temperature sensors and battery cells
310  */
312 
313 /** Lookup table to indicate which voltage inputs are used */
314 extern const uint8_t ltc_voltage_input_used[BS_MAX_SUPPORTED_CELLS];
315 
316 /*========== Extern Function Prototypes =====================================*/
317 
318 /**
319  * @brief converts a raw voltage from multiplexer to a temperature value in
320  * deci &deg;C.
321  * @details The temperatures are read from NTC elements via voltage dividers.
322  * This function implements the look-up table between voltage and
323  * temperature, taking into account the NTC characteristics and the
324  * voltage divider.
325  * @param adcVoltage_mV voltage read from the multiplexer in mV
326  * @return temperature value in deci &deg;C
327  */
328 extern int16_t LTC_Convert_MuxVoltages_to_Temperatures(uint16_t adcVoltage_mV);
329 
330 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
331 
332 #endif /* FOXBMS__LTC_6806_CFG_H_ */
ltc_muxsensortemperatur_cfg
const uint8_t ltc_muxsensortemperatur_cfg[BS_NR_OF_TEMP_SENSORS_PER_MODULE]
Definition: ltc_6813-1_cfg.c:187
spi.h
Headers for the driver for the SPI module.
BS_NR_OF_TEMP_SENSORS_PER_MODULE
#define BS_NR_OF_TEMP_SENSORS_PER_MODULE
number of temperature sensors per battery module
Definition: battery_system_cfg.h:153
LTC_Convert_MuxVoltages_to_Temperatures
int16_t LTC_Convert_MuxVoltages_to_Temperatures(uint16_t adcVoltage_mV)
converts a raw voltage from multiplexer to a temperature value in deci °C.
Definition: ltc_6813-1_cfg.c:229
battery_system_cfg.h
Configuration of the battery system (e.g., number of battery modules, battery cells,...
ltc_defs.h
Headers for the driver for the LTC monitoring chip.
ltc_cfg.h
Headers for the configuration for the LTC monitoring chip.
ltc_mic_dma.h
Headers for the driver for the DMA module for the LTC.
ltc_voltage_input_used
const uint8_t ltc_voltage_input_used[BS_MAX_SUPPORTED_CELLS]
Definition: ltc_6806_cfg.c:63
BS_MAX_SUPPORTED_CELLS
#define BS_MAX_SUPPORTED_CELLS
Defines the maximal number of supported cells per module.