foxBMS  1.2.0
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-03-24 (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 datasheet) */
158 #define LTC_TWAKE_US (300)
159 /** start definition of LTC timings; Tready (see LTC datasheet) */
160 #define LTC_TREADY_US (10)
161 /** start definition of LTC timings; Tidle (see LTC datasheet) */
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 datasheet 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 datasheet 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_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_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_FILTERED_TCYCLE (202)
202 
203 /*
204  * Timings of Voltage Cell and GPIO measurement for a pair of cells or a single GPIO
205  */
206 
207 /**
208  * ~0.201ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Fast Mode
209  * unit: ms
210  */
211 #define LTC_STATEMACH_MEAS_SINGLE_FAST_TCYCLE (1)
212 
213 /**
214  * ~0.405ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Normal Mode
215  * unit: ms
216  */
217 #define LTC_STATEMACH_MEAS_SINGLE_NORMAL_TCYCLE (1)
218 
219 /**
220  * ~34 ms Measurement+Calibration Cycle Time When Starting from the REFUP State in Filtered Mode
221  * unit: ms
222  */
223 #define LTC_STATEMACH_MEAS_SINGLE_FILTERED_TCYCLE (35)
224 
225 /** LTC statemachine sequence error timing in ms */
226 #define LTC_STATEMACH_SEQERRTTIME (5)
227 /** LTC statemachine CRC-transmission error timing in ms */
228 #define LTC_STATEMACH_PECERRTIME (1)
229 
230 /**
231  * Maximum number of re-tries in case of CRC error during the communication with daisy chain
232  * before going into error state
233  */
234 #define LTC_TRANSMIT_PECERRLIMIT (10)
235 
236 /**
237  * Maximum number of re-tries in case of SPI error during the communication with daisy chain
238  * before going into error state
239  */
240 #define LTC_TRANSMIT_SPIERRLIMIT (3)
241 
242 /** If set to 1, check if multiplexers acknowledged transmission */
243 #define LTC_READCOM (0)
244 
245 /**
246  * ------------------- OPEN WIRE CHECK ------------------------
247  * If open-wire check is performed cell voltages and temperatures are not
248  * updated and thus old values can be transmitted on the CAN bus. Check time
249  * is dependent on module configuration and external capacitance. Activate
250  * open-wire check with care! See table below for various measured open-wire
251  * check durations! (set to TRUE or FALSE)
252  */
253 #define LTC_STANDBY_PERIODIC_OPEN_WIRE_CHECK (false)
254 
255 /** Periodic open-wire check time in STANDBY state in ms */
256 #define LTC_STANDBY_OPEN_WIRE_PERIOD_ms (600000)
257 
258 /** open-wire check in normal mode (set to true or false) */
259 #define LTC_NORMAL_PERIODIC_OPEN_WIRE_CHECK (false)
260 
261 /** Periodic open-wire check time in NORMAL state in ms */
262 #define LTC_NORMAL_OPEN_WIRE_PERIOD_ms (600000)
263 
264 /** open-wire check in charge mode (set to true or false) */
265 #define LTC_CHARGE_PERIODIC_OPEN_WIRE_CHECK (false)
266 
267 /** Periodic open-wire check time in CHARGE state in ms */
268 #define LTC_CHARGE_OPEN_WIRE_PERIOD_ms (600000)
269 
270 /** Periodic open-wire check time in ERROR state in ms */
271 #define LTC_ERROR_OPEN_WIRE_PERIOD_ms (30000)
272 
273 /**
274  * Number of required ADOW commands because of external C-Pin capacitance and
275  * the respective duration to perform an open wire check for 14 modules with
276  * 12 cells each. During this time no cell voltages and temperatures are measured!
277  * +----------------+--------------+---------------+----------+----------+
278  * | External C pin | Normal mode | Filtered mode | Duration | Duration |
279  * | capacitance | | | normal | filtered |
280  * | ---------------+--------------+---------------+----------+----------+
281  * | <= 10nF | 2 | 2 | 32ms | 828ms |
282  * | 100nF | 10 | 2 | 112ms | 828ms |
283  * | 1uF | 100 | 2 | 1012ms | 828ms |
284  * | C | 1.5+(C/10nF) | 2 | | |
285  * +----------------+--------------+---------------+----------+----------+
286  */
287 #define LTC_NMBR_REQ_ADOW_COMMANDS (2)
288 
289 /**
290  * Transmit functions
291  * @{
292  */
293 #define LTC_TransmitWakeUp(spi_ltcInterface) SPI_TransmitDummyByte(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US)
294 #define LTC_TransmitI2cCommand(spi_ltcInterface, txbuf) \
295  SPI_TransmitDataWithDummy(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US, txbuf, 4 + 9)
296 #define LTC_TransmitCommand(spi_ltcInterface, command) \
297  SPI_TransmitDataWithDummy(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US, command, 4)
298 #define LTC_TransmitReceiveData(spi_ltcInterface, txbuf, rxbuf, length) \
299  SPI_TransmitReceiveDataWithDummyDma(spi_ltcInterface, LTC_SPI_WAKEUP_WAIT_TIME_US, txbuf, rxbuf, length)
300 /**@}*/
301 
302 /*========== Extern Constant and Variable Declarations ======================*/
303 
304 /**
305  * Definition of the multiplexer measurement sequence
306  */
308 
309 /**
310  * On the foxBMS slave board there are 6 multiplexer inputs dedicated to temperature
311  * sensors by default.
312  * Lookup table between temperature sensors and battery cells
313  */
315 
316 /** Lookup table to indicate which voltage inputs are used */
317 extern const uint8_t ltc_voltage_input_used[BS_MAX_SUPPORTED_CELLS];
318 
319 /*========== Extern Function Prototypes =====================================*/
320 
321 /**
322  * @brief converts a raw voltage from multiplexer to a temperature value in
323  * deci &deg;C.
324  * @details The temperatures are read from NTC elements via voltage dividers.
325  * This function implements the look-up table between voltage and
326  * temperature, taking into account the NTC characteristics and the
327  * voltage divider.
328  * @param adcVoltage_mV voltage read from the multiplexer in mV
329  * @return temperature value in deci &deg;C
330  */
331 extern int16_t LTC_Convert_MuxVoltages_to_Temperatures(uint16_t adcVoltage_mV);
332 
333 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
334 
335 #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.