foxBMS  1.2.1
The foxBMS Battery Management System API Documentation
ltc_6813-1_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_6813-1_cfg.h
44  * @author foxBMS Team
45  * @date 2015-02-18 (date of creation)
46  * @updated 2021-12-08 (date of last update)
47  * @ingroup DRIVERS_CONFIGURATION
48  * @prefix LTC
49  *
50  * @brief Header for the configuration for the LTC 6804-1 6811-1, 6812-1,
51  * and 6813-1 monitoring IC.
52  *
53  */
54 
55 #ifndef FOXBMS__LTC_6813_1_CFG_H_
56 #define FOXBMS__LTC_6813_1_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 #if SLAVE_BOARD_VERSION == 1
78 #elif SLAVE_BOARD_VERSION == 2
79 #else
80 #error Please select the slave board version you want to use. Configuration file: \src\module\config\ltc_cfg.h
81 #endif
82 
83 /**
84  * If set to 0 LTC driver is configured to use PCA8574 port expander
85  * If set to 1 LTC driver is configured to use TCA6408A port expander
86  */
87 #define LTC_PORTEXPANDER_VERSION (1u)
88 
89 /** Address of TI port expander (0 or 1) */
90 #define LTC_PORTEXPANDER_ADR_TI (0u)
91 
92 /** Controls if PEC should be discarded (true) or not (false) */
93 #define LTC_DISCARD_PEC (false)
94 
95 /* set to true or false */
96 #define LTC_GOTO_MUX_CHECK (true)
97 
98 /* set to true or false */
99 #define LTC_DISCARD_MUX_CHECK (false)
100 
101 /** Number of multiplexer used per LTC-IC */
102 #define LTC_N_MUX_PER_LTC (3u)
103 
104 /** Number of channels per multiplexer */
105 #define LTC_N_MUX_CHANNELS_PER_MUX (8u)
106 
107 /** Number of multiplexer measurements per LTC cycle */
108 #define LTC_NUMBER_OF_MUX_MEASUREMENTS_PER_CYCLE (8u)
109 
110 /** Number of multiplexed channels per LTC-IC */
111 #define LTC_N_MUX_CHANNELS_PER_LTC (LTC_N_MUX_PER_LTC * LTC_N_MUX_CHANNELS_PER_MUX)
112 
113 /** Number of LTC-ICs per battery module */
114 #define LTC_NUMBER_OF_LTC_PER_MODULE (1u)
115 
116 /** Open-wire detection threshold */
117 #define LTC_ADOW_THRESHOLD (-400)
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 /** LTC statemachine short time definition in ms */
168 #define LTC_STATEMACH_SHORTTIME (1)
169 
170 /**
171  * time for the first initialization of the daisy chain
172  * see LTC6804 data sheet page 41
173  */
174 #define LTC_STATEMACH_DAISY_CHAIN_FIRST_INITIALIZATION_TIME ((LTC_TWAKE_US * LTC_N_LTC) / 1000)
175 /**
176  * time for the second initialization of the daisy chain
177  * see LTC6804 data sheet page 41
178  */
179 #define LTC_STATEMACH_DAISY_CHAIN_SECOND_INITIALIZATION_TIME ((LTC_TREADY_US * LTC_N_LTC) / 1000)
180 
181 /*
182  * Timings of Voltage Cell and GPIO measurement for all cells or all GPIO
183  */
184 
185 /**
186  * ~1.1ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
187  * unit: ms
188  */
189 #define LTC_STATEMACH_MEAS_ALL_CELLS_FAST_TCYCLE (2)
190 
191 /**
192  * ~2.3ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
193  * unit: ms
194  */
195 #define LTC_STATEMACH_MEAS_ALL_CELLS_NORMAL_TCYCLE (3)
196 
197 /**
198  * ~201ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
199  * unit: ms
200  */
201 #define LTC_STATEMACH_MEAS_ALL_CELLS_FILTERED_TCYCLE (202)
202 
203 /**
204  * ~203us Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
205  * unit: ms
206  */
207 #define LTC_STATEMACH_MEAS_TWO_CELLS_FAST_TCYCLE (1)
208 
209 /**
210  * ~407us Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
211  * unit: ms
212  */
213 #define LTC_STATEMACH_MEAS_TWO_CELLS_NORMAL_TCYCLE (1)
214 
215 /**
216  * ~34ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
217  * unit: ms
218  */
219 #define LTC_STATEMACH_MEAS_TWO_CELLS_FILTERED_TCYCLE (35)
220 
221 /*
222  * Timings of Voltage Cell and GPIO measurement for a pair of cells or a single GPIO
223  */
224 
225 /**
226  * ~1.8ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
227  * unit: ms
228  */
229 #define LTC_STATEMACH_MEAS_ALL_GPIOS_FAST_TCYCLE (2)
230 
231 /**
232  * ~3.9ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
233  * unit: ms
234  */
235 #define LTC_STATEMACH_MEAS_ALL_GPIOS_NORMAL_TCYCLE (4)
236 
237 /**
238  * ~335ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
239  * unit: ms
240  */
241 #define LTC_STATEMACH_MEAS_ALL_GPIOS_FILTERED_TCYCLE (336)
242 
243 /**
244  * ~380us Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
245  * unit: ms
246  */
247 #define LTC_STATEMACH_MEAS_SINGLE_GPIO_FAST_TCYCLE (1)
248 
249 /**
250  * ~788us Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
251  * unit: ms
252  */
253 #define LTC_STATEMACH_MEAS_SINGLE_GPIO_NORMAL_TCYCLE (1)
254 
255 /**
256  * ~67.1ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
257  * unit: ms
258  */
259 #define LTC_STATEMACH_MEAS_SINGLE_GPIO_FILTERED_TCYCLE (68)
260 
261 /** LTC statemachine sequence error timing in ms */
262 #define LTC_STATEMACH_SEQERRTTIME (5)
263 /** LTC statemachine CRC-transmission error timing in ms */
264 #define LTC_STATEMACH_PECERRTIME (1)
265 
266 /**
267  * Maximum number of re-tries in case of CRC error during the communication with daisy chain
268  * before going into error state
269  */
270 #define LTC_TRANSMIT_PECERRLIMIT (10)
271 
272 /**
273  * Maximum number of re-tries in case of SPI error during the communication with daisy chain
274  * before going into error state
275  */
276 #define LTC_TRANSMIT_SPIERRLIMIT (3)
277 
278 /** If set to 1, check if multiplexers acknowledged transmission */
279 #define LTC_READCOM (0)
280 
281 /**
282  * ------------------- OPEN WIRE CHECK ------------------------
283  * If open-wire check is performed cell voltages and temperatures are not
284  * updated and thus old values can be transmitted on the CAN bus. Check time
285  * is dependent on module configuration and external capacitance. Activate
286  * open-wire check with care! See table below for various measured open-wire
287  * check durations! (set to TRUE or FALSE)
288  */
289 #define LTC_STANDBY_PERIODIC_OPEN_WIRE_CHECK (false)
290 
291 /** Periodic open-wire check time in STANDBY state in ms */
292 #define LTC_STANDBY_OPEN_WIRE_PERIOD_ms (600000)
293 
294 /** open-wire check in normal mode (set to true or false) */
295 #define LTC_NORMAL_PERIODIC_OPEN_WIRE_CHECK (false)
296 
297 /** Periodic open-wire check time in NORMAL state in ms */
298 #define LTC_NORMAL_OPEN_WIRE_PERIOD_ms (600000)
299 
300 /** open-wire check in charge mode (set to true or false) */
301 #define LTC_CHARGE_PERIODIC_OPEN_WIRE_CHECK (false)
302 
303 /** Periodic open-wire check time in CHARGE state in ms */
304 #define LTC_CHARGE_OPEN_WIRE_PERIOD_ms (600000)
305 
306 /** Periodic open-wire check time in ERROR state in ms */
307 #define LTC_ERROR_OPEN_WIRE_PERIOD_ms (30000)
308 
309 /**
310  * Number of required ADOW commands because of external C-Pin capacitance and
311  * the respective duration to perform an open wire check for 14 modules with
312  * 12 cells each. During this time no cell voltages and temperatures are measured!
313  * +----------------+--------------+---------------+----------+----------+
314  * | External C pin | Normal mode | Filtered mode | Duration | Duration |
315  * | capacitance | | | normal | filtered |
316  * | ---------------+--------------+---------------+----------+----------+
317  * | <= 10nF | 2 | 2 | 32ms | 828ms |
318  * | 100nF | 10 | 2 | 112ms | 828ms |
319  * | 1uF | 100 | 2 | 1012ms | 828ms |
320  * | C | 1.5+(C/10nF) | 2 | | |
321  * +----------------+--------------+---------------+----------+----------+
322  */
323 #define LTC_NMBR_REQ_ADOW_COMMANDS (2)
324 
325 /**
326  * Transmit functions
327  * @{
328  */
329 #define LTC_TransmitWakeUp(spi_ltcInterface) SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US)
330 #define LTC_TransmitI2cCommand(spi_ltcInterface, txbuf) \
331  SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US); \
332  SPI_TransmitData(spi_ltcInterface, txbuf, 4 + 9)
333 #define LTC_TransmitCommand(spi_ltcInterface, command) \
334  SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US); \
335  SPI_TransmitData(spi_ltcInterface, command, 4)
336 #define LTC_TransmitReceiveData(spi_ltcInterface, txbuf, rxbuf, length) \
337  SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US); \
338  SPI_TransmitReceiveDataDma(spi_ltcInterface, txbuf, rxbuf, length)
339 /**@}*/
340 
341 /*========== Extern Constant and Variable Declarations ======================*/
342 
343 /**
344  * Definition of the multiplexer measurement sequence
345  */
347 
348 /**
349  * On the foxBMS slave board there are 6 multiplexer inputs dedicated to temperature
350  * sensors by default.
351  * Lookup table between temperature sensors and battery cells
352  */
354 
355 /** Lookup table to indicate which voltage inputs are used */
356 extern const uint8_t ltc_voltage_input_used[BS_MAX_SUPPORTED_CELLS];
357 
358 /*========== Extern Function Prototypes =====================================*/
359 
360 /**
361  * @brief converts a raw voltage from multiplexer to a temperature value in
362  * deci &deg;C.
363  * @details The temperatures are read from NTC elements via voltage dividers.
364  * This function implements the look-up table between voltage and
365  * temperature, taking into account the NTC characteristics and the
366  * voltage divider.
367  * @param adcVoltage_mV voltage read from the multiplexer in mV
368  * @return temperature value in deci &deg;C
369  */
370 extern int16_t LTC_Convert_MuxVoltages_to_Temperatures(uint16_t adcVoltage_mV);
371 
372 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
373 
374 #endif /* FOXBMS__LTC_6813_1_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
LTC_MUX_SEQUENCE_s ltc_mux_seq
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.