foxBMS  1.2.0
The foxBMS Battery Management System API Documentation
ltc_6806_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 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_afe_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_ */
Configuration of the battery system (e.g., number of battery modules, battery cells,...
#define BS_MAX_SUPPORTED_CELLS
Defines the maximal number of supported cells per module.
#define BS_NR_OF_TEMP_SENSORS_PER_MODULE
number of temperature sensors per battery module
int16_t LTC_Convert_MuxVoltages_to_Temperatures(uint16_t adcVoltage_mV)
converts a raw voltage from multiplexer to a temperature value in deci °C.
const uint8_t ltc_muxsensortemperatur_cfg[BS_NR_OF_TEMP_SENSORS_PER_MODULE]
const uint8_t ltc_voltage_input_used[BS_MAX_SUPPORTED_CELLS]
Definition: ltc_6806_cfg.c:63
Headers for the driver for the DMA module for the LTC.
Headers for the configuration for the LTC monitoring chip.
Headers for the driver for the LTC monitoring chip.
Headers for the driver for the SPI module.