foxBMS  1.3.0
The foxBMS Battery Management System API Documentation
ltc_6806_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 ltc_6806_cfg.h
44  * @author foxBMS Team
45  * @date 2015-02-18 (date of creation)
46  * @updated 2022-05-30 (date of last update)
47  * @version v1.3.0
48  * @ingroup DRIVERS_CONFIGURATION
49  * @prefix LTC
50  *
51  * @brief Header for the configuration for the LTC 6806 monitoring IC
52  *
53  */
54 
55 #ifndef FOXBMS__LTC_6806_CFG_H_
56 #define FOXBMS__LTC_6806_CFG_H_
57 
58 /*========== Includes =======================================================*/
59 /* clang-format off */
60 #include "ltc_cfg.h"
61 /* clang-format on */
62 
63 #include "ltc_defs.h"
64 #include "battery_system_cfg.h"
65 
66 #include "ltc_afe_dma.h"
67 #include "spi.h"
68 
69 /*========== Macros and Definitions =========================================*/
70 /**
71  * @ingroup CONFIG_LTC
72  * If set to 1 LTC driver is configured to use foxBMS slave boards version 1.x
73  * If set to 2 LTC driver is configured to use foxBMS slave boards version 2.x
74  */
75 #define SLAVE_BOARD_VERSION (2)
76 
77 /**
78  * If set to 0 LTC driver is configured to use PCA8574 port expander
79  * If set to 1 LTC driver is configured to use TCA6408A port expander
80  */
81 #define LTC_PORTEXPANDER_VERSION (1)
82 
83 /**
84  * Address of TI port expander (0 or 1)
85  */
86 #define LTC_PORTEXPANDER_ADR_TI (0)
87 
88 /** Controls if PEC should be discarded (true) or not (false) */
89 #define LTC_DISCARD_PEC (false)
90 
91 /** Number of multiplexer used per LTC-IC */
92 #define LTC_N_MUX_PER_LTC (3)
93 
94 /** Number of channels per multiplexer */
95 #define LTC_N_MUX_CHANNELS_PER_MUX (8)
96 
97 /** Number of multiplexer measurements per LTC cycle */
98 #define LTC_NUMBER_OF_MUX_MEASUREMENTS_PER_CYCLE (8)
99 
100 /** Number of multiplexed channels per LTC-IC */
101 #define LTC_N_MUX_CHANNELS_PER_LTC (LTC_N_MUX_PER_LTC * LTC_N_MUX_CHANNELS_PER_MUX)
102 
103 /** Number of LTC-ICs per battery module */
104 #define LTC_NUMBER_OF_LTC_PER_MODULE (1u)
105 
106 /**
107  * Voltage measurement range for fuel cells
108  * LSB = 1.5 mV if HIRNG = 0u
109  * LSB = 3.0 mV if HIRNG = 1u
110  */
111 #define LTC_HIRNG (0u)
112 
113 /** Open-wire voltage measurement time for fuel cells */
114 #define LTC_FUEL_CELL_ADOW_TIME_MS (100U + 1U)
115 
116 /** Open-wire detection threshold */
117 #define LTC_ADOW_THRESHOLD (-200)
118 
119 /**
120  * Measurement modus for voltages, possible values:
121  * - LTC_ADCMODE_NORMAL_DCP0
122  * - LTC_ADCMODE_FILTERED_DCP0
123  * - LTC_ADCMODE_FAST_DCP0
124  */
125 #define LTC_VOLTAGE_MEASUREMENT_MODE (LTC_ADCMODE_NORMAL_DCP0)
126 
127 /**
128  * Measurement modus for GPIOs, possible values:
129  * - LTC_ADCMODE_NORMAL_DCP0
130  * - LTC_ADCMODE_FILTERED_DCP0
131  * - LTC_ADCMODE_FAST_DCP0
132  */
133 #define LTC_GPIO_MEASUREMENT_MODE (LTC_ADCMODE_NORMAL_DCP0)
134 
135 /**
136  * Measurement modus for Open-wire check, possible values:
137  * - LTC_ADCMODE_NORMAL_DCP0
138  * - LTC_ADCMODE_FILTERED_DCP0
139  */
140 #define LTC_OW_MEASUREMENT_MODE (LTC_ADCMODE_NORMAL_DCP0)
141 
142 /**
143  * Timeout in milliseconds added to the transmission time for interrupt-based
144  * SPI transmission.
145  */
146 #define LTC_TRANSMISSION_TIMEOUT (10)
147 
148 /**
149  * SPI1 is used for communication with LTC
150  * @{
151  */
152 #define LTC_SPI_HANDLE &spi_devices[0]
153 #define LTC_SPI_INSTANCE *LTC_SPI_HANDLE.Instance
154 #define LTC_SPI_PRESCALER *LTC_SPI_HANDLE.Init.BaudRatePrescaler
155 /**@}*/
156 
157 /** start definition of LTC timings; Twake (see LTC data sheet) */
158 #define LTC_TWAKE_US (300)
159 /** start definition of LTC timings; Tready (see LTC data sheet) */
160 #define LTC_TREADY_US (10)
161 /** start definition of LTC timings; Tidle (see LTC data sheet) */
162 #define LTC_TIDLE_US (6700)
163 
164 /** LTC SPI wakeup time */
165 #define LTC_SPI_WAKEUP_WAIT_TIME_US (30U)
166 
167 /** Time to measure all fuel cells in normal mode 10280 µs */
168 #define LTC_FUELCELL_NORMAL_ALL_CELLS_MS (11)
169 
170 /** LTC statemachine short time definition in ms */
171 #define LTC_STATEMACH_SHORTTIME (1)
172 
173 /**
174  * time for the first initialization of the daisy chain
175  * see LTC6804 data sheet page 41
176  */
177 #define LTC_STATEMACH_DAISY_CHAIN_FIRST_INITIALIZATION_TIME ((LTC_TWAKE_US * LTC_N_LTC) / 1000)
178 /**
179  * time for the second initialization of the daisy chain
180  * see LTC6804 data sheet page 41
181  */
182 #define LTC_STATEMACH_DAISY_CHAIN_SECOND_INITIALIZATION_TIME ((LTC_TREADY_US * LTC_N_LTC) / 1000)
183 
184 /*
185  * Timings of Voltage Cell and GPIO measurement for all cells or all GPIO
186  */
187 
188 /**
189  * ~1.1ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
190  * unit: ms
191  */
192 #define LTC_STATEMACH_MEAS_ALL_FAST_TCYCLE (2)
193 
194 /**
195  * ~2.3ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
196  * unit: ms
197  */
198 #define LTC_STATEMACH_MEAS_ALL_NORMAL_TCYCLE (3)
199 
200 /**
201  * ~201ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
202  * unit: ms
203  */
204 #define LTC_STATEMACH_MEAS_ALL_FILTERED_TCYCLE (202)
205 
206 /*
207  * Timings of Voltage Cell and GPIO measurement for a pair of cells or a single GPIO
208  */
209 
210 /**
211  * ~0.201ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
212  * unit: ms
213  */
214 #define LTC_STATEMACH_MEAS_SINGLE_FAST_TCYCLE (1)
215 
216 /**
217  * ~0.405ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
218  * unit: ms
219  */
220 #define LTC_STATEMACH_MEAS_SINGLE_NORMAL_TCYCLE (1)
221 
222 /**
223  * ~34 ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
224  * unit: ms
225  */
226 #define LTC_STATEMACH_MEAS_SINGLE_FILTERED_TCYCLE (35)
227 
228 /** LTC statemachine sequence error timing in ms */
229 #define LTC_STATEMACH_SEQERRTTIME (5)
230 /** LTC statemachine CRC-transmission error timing in ms */
231 #define LTC_STATEMACH_PECERRTIME (1)
232 
233 /**
234  * Maximum number of re-tries in case of CRC error during the communication with daisy chain
235  * before going into error state
236  */
237 #define LTC_TRANSMIT_PECERRLIMIT (10)
238 
239 /**
240  * Maximum number of re-tries in case of SPI error during the communication with daisy chain
241  * before going into error state
242  */
243 #define LTC_TRANSMIT_SPIERRLIMIT (3)
244 
245 /** If set to 1, check if multiplexers acknowledged transmission */
246 #define LTC_READCOM (0)
247 
248 /**
249  * Number of required ADOW commands because of external C-Pin capacitance and
250  * the respective duration to perform an open wire check for 14 modules with
251  * 12 cells each. During this time no cell voltages and temperatures are measured!
252  * +----------------+--------------+---------------+----------+----------+
253  * | External C pin | Normal mode | Filtered mode | Duration | Duration |
254  * | capacitance | | | normal | filtered |
255  * | ---------------+--------------+---------------+----------+----------+
256  * | <= 10nF | 2 | 2 | 32ms | 828ms |
257  * | 100nF | 10 | 2 | 112ms | 828ms |
258  * | 1uF | 100 | 2 | 1012ms | 828ms |
259  * | C | 1.5+(C/10nF) | 2 | | |
260  * +----------------+--------------+---------------+----------+----------+
261  */
262 #define LTC_NMBR_REQ_ADOW_COMMANDS (2)
263 
264 /**
265  * Transmit functions
266  * @{
267  */
268 #define LTC_TransmitWakeUp(spi_ltcInterface) SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US)
269 #define LTC_TransmitI2cCommand(spi_ltcInterface, txbuf) \
270  SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US); \
271  SPI_TransmitData(spi_ltcInterface, txbuf, 4 + 9)
272 #define LTC_TransmitCommand(spi_ltcInterface, command) \
273  SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US); \
274  SPI_TransmitData(spi_ltcInterface, command, 4)
275 #define LTC_TransmitReceiveData(spi_ltcInterface, txbuf, rxbuf, length) \
276  SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US); \
277  SPI_TransmitReceiveDataDma(spi_ltcInterface, txbuf, rxbuf, length)
278 /**@}*/
279 
280 /*========== Extern Constant and Variable Declarations ======================*/
281 
282 /**
283  * On the foxBMS slave board there are 6 multiplexer inputs dedicated to temperature
284  * sensors by default.
285  * Lookup table between temperature sensors and battery cells
286  */
288 
289 /** Lookup table to indicate which voltage inputs are used */
290 extern const uint8_t ltc_voltage_input_used[BS_MAX_SUPPORTED_CELLS];
291 
292 /*========== Extern Function Prototypes =====================================*/
293 
294 /**
295  * @brief converts a raw voltage from multiplexer to a temperature value in
296  * deci &deg;C.
297  * @details The temperatures are read from NTC elements via voltage dividers.
298  * This function implements the look-up table between voltage and
299  * temperature, taking into account the NTC characteristics and the
300  * voltage divider.
301  * @param adcVoltage_mV voltage read from the multiplexer in mV
302  * @return temperature value in deci &deg;C
303  */
304 extern int16_t LTC_ConvertMuxVoltagesToTemperatures(uint16_t adcVoltage_mV);
305 
306 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
307 
308 #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
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:64
int16_t LTC_ConvertMuxVoltagesToTemperatures(uint16_t adcVoltage_mV)
converts a raw voltage from multiplexer to a temperature value in deci °C.
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.