foxBMS - Unit Tests  1.1.0
The foxBMS Unit Tests API Documentation
adc.c
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 adc.c
44  * @author foxBMS Team
45  * @date 2019-01-07 (date of creation)
46  * @updated 2021-07-14 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix ADC
49  *
50  * @brief Driver for the ADC module.
51  *
52  */
53 
54 /*========== Includes =======================================================*/
55 #include "adc.h"
56 
57 #include "beta.h"
58 #include "database.h"
59 #include "epcos_b57251v5103j060.h"
60 #include "io.h"
61 #include "spi.h"
62 
63 /*========== Macros and Definitions =========================================*/
64 
65 /** scaling factor for the conversion of a measurement value to a temperature */
66 #define ADC_TEMPERATURE_FACTOR (10.0f)
67 
68 /**
69  * Type of temperature sensors
70  */
72  ADC0_TEMPERATURE_SENSOR, /*!< First ADC (ADC0) */
73  ADC1_TEMPERATURE_SENSOR, /*!< Second ADC (ADC1) */
75 
76 /*========== Static Constant and Variable Definitions =======================*/
77 
78 /**
79  * @brief describes the current state of the conversion
80  * @details This variable is used as a state-variable for switching through the
81  * steps of a conversion.
82  */
83 static uint8_t adc_conversionState = ADC_INIT;
84 
85 /** NULL command sent to initialize the ADC */
86 static uint16_t adc_txNull[SINGLE_MESSAGE_LENGTH] = {0x0000u, 0x0000u};
87 
88 /**
89  * Unlock command for the ADC
90  * When ADC is locked, regsiters cannot be written
91  */
92 static uint16_t adc_txUnlockCommand[SINGLE_MESSAGE_LENGTH] = {0x0655u, 0x0000u};
93 
94 /**
95  * Lock command the ADC
96  * When ADC is locked, regsiters cannot be written
97  */
98 static uint16_t adc_txLockCommand[SINGLE_MESSAGE_LENGTH] = {0x0555u, 0x0000u};
99 
100 /** The wake-up command starts the conversions by the ADC */
101 static uint16_t adc_txWakeupCommand[SINGLE_MESSAGE_LENGTH] = {0x0033u, 0x0000u};
102 
103 /** This command is used to read registers */
104 static uint16_t adc_txReadRegisterCommand[SINGLE_MESSAGE_LENGTH] = {0x2F00u, 0x0000u};
105 
106 /** This command is used to write registers */
107 static uint16_t adc_txWriteRegisterCommand[SINGLE_MESSAGE_LENGTH] = {0x4F0Fu, 0x0000u};
108 
109 /**
110  * This is a generic purpose receive buffer.
111  * It is used to read the answer of the ADC to the commands
112  * defined above.
113  */
114 static uint16_t adc_rxReadSingleMessage[SINGLE_MESSAGE_LENGTH] = {0x0000u, 0x0000u};
115 
116 /**
117  * This message is used to read conversion results
118  * It consists of NULL commands. When receiving NULL commands,
119  * the ADC outputs conversion data on the MasterInSlaveOut line.
120  */
121 static uint16_t adc_txConvert[CONVERT_LENGTH] =
122  {0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u};
123 
124 /** This message is used to get the result of conversions */
125 static uint16_t adc_rxConvert[CONVERT_LENGTH] =
126  {0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u, 0x0000u};
127 
128 /** Voltages measured by the 4 channels of ADC0 */
129 static float adc_adc0Voltage[4] = {0.0f, 0.0f, 0.0f, 0.0f};
130 /** Voltages measured by the 4 channels of ADC1 */
131 static float adc_adc1Voltage[4] = {0.0f, 0.0f, 0.0f, 0.0f};
132 /** LSB of ADC0, used to convert raw measurement to voltage in V */
133 static float adc_lsb1 = 0.0f;
134 /** LSB of ADC1, used to convert raw measurement to voltage in V */
135 static float adc_lsb2 = 0.0f;
136 
137 /** local copy of the adc temperature table */
139 
140 /*========== Extern Constant and Variable Definitions =======================*/
141 
142 /*========== Static Function Prototypes =====================================*/
143 
144 /** transmission wrapper for the SPI communication to the ADC */
146  uint32 blocksize,
147  uint16 *pTxBuffer,
148  uint16 *pRxBuffer,
149  SPI_INTERFACE_CONFIG_s *pSpiInterface);
150 
151 /**
152  * @brief converts a raw voltage from ADC to a temperature value in Celsius.
153  *
154  * The temperatures are read from NTC elements via voltage dividers.
155  * This function implements the look-up table between voltage and temperature,
156  * taking into account the NTC characteristics and the voltage divider.
157  *
158  * @param v_adc_V voltage read from ADC in V
159  * @param TsensorType sensor type, dependent on ADC used (ADC0 or ADC1)
160  *
161  * @return temperature value in deci &deg;C
162  */
163 static float ADC_ConvertVoltagesToTemperatures(float v_adc_V, ADC_TEMPERATURE_SENSOR_TYPE_e TsensorType);
164 
165 /*========== Static Function Implementations ================================*/
166 
168  uint32 blocksize,
169  uint16 *pTxBuffer,
170  uint16 *pRxBuffer,
171  SPI_INTERFACE_CONFIG_s *pSpiInterface) {
172  FAS_ASSERT(pTxBuffer != NULL_PTR);
173  FAS_ASSERT(pRxBuffer != NULL_PTR);
174  FAS_ASSERT(pSpiInterface != NULL_PTR);
175 
176  return SPI_TransmitReceiveData(pSpiInterface, pTxBuffer, pRxBuffer, blocksize);
177 }
178 
179 static float ADC_ConvertVoltagesToTemperatures(float v_adc_V, ADC_TEMPERATURE_SENSOR_TYPE_e TsensorType) {
180  float temperature_degC = 0.0f;
181  if (TsensorType == ADC0_TEMPERATURE_SENSOR) {
182  temperature_degC = ADC_TEMPERATURE_FACTOR * TS_Epc00GetTemperatureFromLut((uint16_t)(v_adc_V * 1000.0f));
183  } else if (TsensorType == ADC1_TEMPERATURE_SENSOR) {
184  temperature_degC = ADC_TEMPERATURE_FACTOR * BETA_GetTemperatureFromBeta((uint16_t)(v_adc_V * 1000.0f));
185  } else {
186  temperature_degC = ADC_TEMPERATURE_FACTOR * v_adc_V;
187  }
188 
189  return (10.0f * temperature_degC); /* Convert to deci &deg;C */
190 }
191 
192 /*========== Extern Function Implementations ================================*/
193 
194 void ADC_Initialize(void) {
195  /* set reset pin to output */
196  ADC_HET1_GIO->DIR |= (uint32)((uint32)1u << ADC_HET1_RESET_PIN);
197 
198  /* first set reset pin to 0 */
200  /* wait after pin toggle */
201  for (uint8_t i = 0u; i < 20u; i++) {
202  }
203  /* set reset pin to 1 to go out of reset */
205 
206  /* LSB computation, datasheet equation 9 page 38 */
207  adc_lsb1 = (2 * ADC_VREF_1 / ADC_GAIN) / (16777216.0f);
208  adc_lsb2 = (2 * ADC_VREF_2 / ADC_GAIN) / (16777216.0f);
209 }
210 
211 void ADC_Control(void) {
212  switch (adc_conversionState) {
213  case ADC_INIT:
214  /* set reset pin to output */
215  ADC_HET1_GIO->DIR |= (uint32)((uint32)1u << ADC_HET1_RESET_PIN);
216  /* first set reset pin to 0 */
219  break;
220 
221  case ADC_ENDINIT:
222  /* set reset pin to 1 to go out of reset */
224  /* LSB computation, datasheet equation 9 page 38 */
225  adc_lsb1 = (2 * ADC_VREF_1 / ADC_GAIN) / (16777216.0f);
226  adc_lsb2 = (2 * ADC_VREF_2 / ADC_GAIN) / (16777216.0f);
228  break;
229 
230  /* Start initialization procedure, datasheet figure 106 page 79 */
231  case ADC_READY:
233  /* if device 1 is ready after startup */
234  if (adc_rxReadSingleMessage[0] == 0xFF04u) {
236  /* if device 2 is ready after startup */
237  if (adc_rxReadSingleMessage[0] == 0xFF04u) {
239  }
240  }
241  break;
242 
243  case ADC_UNLOCK:
247  break;
248 
249  case ADC_UNLOCKED:
251  /* if unlock message received by ADC 1*/
252  if (adc_rxReadSingleMessage[0] == 0x0655u) {
254  /* if unlock message received by ADC 2*/
255  if (adc_rxReadSingleMessage[0] == 0x0655u) {
257  }
258  }
259  break;
260 
261  case ADC_WRITE_ADC_ENA:
262  ADC_Transmit(
264  ADC_Transmit(
267  break;
268 
269  case ADC_READ_ADC_ENA:
273  break;
274 
275  case ADC_CHECK_ADC_ENA:
276  /* If register not written successfully, retry */
279  /* if ADC 1 register written successfully */
280  if ((adc_rxReadSingleMessage[0] & 0xFFu) == 0x0Fu) {
282  /* if ADC 1 register written successfully */
283  if ((adc_rxReadSingleMessage[0] & 0xFFu) == 0x0Fu) {
285  }
286  }
287  break;
288 
289  case ADC_WAKEUP:
293  break;
294 
295  case ADC_LOCK:
299  break;
300  /* end initialization procedure, datasheet figure 106 page 79 */
301 
302  /* To read channel data (i.e., measured voltages), send null message */
303  case ADC_CONVERT_1:
304  /* The first 3 voltages are the NTCs located on the master board */
306  for (uint8_t i = 0u; i < ADC_NUMBER_OF_CHANNELS; i++) {
307  /* datasheet SBAS590D -MARCH 2016-REVISED JANUARY 2018 */
308  /* ADC in 32 bit mode (M1 tied to IOVDD via 1kOhm), 24 bits output by ADC, datasheet page 38 */
309  adc_adc0Voltage[i] = (adc_rxConvert[2u + (2u * i)] << 8u) |
310  ((adc_rxConvert[3u + (2u * i)] >> 8u) & 0xFFu);
312  }
315  for (uint8_t i = 0u; i < BS_NR_OF_TEMP_SENSORS_ON_ADC0; i++) {
318  }
320  break;
321 
322  case ADC_CONVERT_2:
323  /* The first 3 voltages are the external NTCs connected to the master board */
325  for (uint8_t i = 0u; i < ADC_NUMBER_OF_CHANNELS; i++) {
326  /* ADC in 32 bit mode (M1 tied to IOVDD via 1kOhm), 24 bits output by ADC, datasheet page 38 */
327  adc_adc1Voltage[i] = (adc_rxConvert[2u + (2u * i)] << 8u) |
328  ((adc_rxConvert[3u + (2u * i)] >> 8u) & 0xFFu);
330  }
333  for (uint8_t i = 0u; i < BS_NR_OF_TEMP_SENSORS_ON_ADC1; i++) {
336  }
338  break;
339 
340  default:
341  /* invalid state */
343  break;
344  }
345 }
346 
347 /*========== Externalized Static Function Implementations (Unit Test) =======*/
static float adc_lsb2
Definition: adc.c:135
static float adc_adc0Voltage[4]
Definition: adc.c:129
static uint16_t adc_txConvert[CONVERT_LENGTH]
Definition: adc.c:121
#define ADC_TEMPERATURE_FACTOR
Definition: adc.c:66
static float adc_adc1Voltage[4]
Definition: adc.c:131
static uint16_t adc_txLockCommand[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:98
ADC_TEMPERATURE_SENSOR_TYPE
Definition: adc.c:71
@ ADC1_TEMPERATURE_SENSOR
Definition: adc.c:73
@ ADC0_TEMPERATURE_SENSOR
Definition: adc.c:72
static uint16_t adc_txNull[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:86
void ADC_Control(void)
determines which ADC is measured and stores result in database.
Definition: adc.c:211
static uint16_t adc_rxConvert[CONVERT_LENGTH]
Definition: adc.c:125
enum ADC_TEMPERATURE_SENSOR_TYPE ADC_TEMPERATURE_SENSOR_TYPE_e
static uint8_t adc_conversionState
describes the current state of the conversion
Definition: adc.c:83
void ADC_Initialize(void)
initializes the ADC devices. It is called during startup.
Definition: adc.c:194
static uint16_t adc_txReadRegisterCommand[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:104
static float adc_lsb1
Definition: adc.c:133
static uint16_t adc_txWakeupCommand[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:101
static float ADC_ConvertVoltagesToTemperatures(float v_adc_V, ADC_TEMPERATURE_SENSOR_TYPE_e TsensorType)
converts a raw voltage from ADC to a temperature value in Celsius.
Definition: adc.c:179
static uint16_t adc_txUnlockCommand[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:92
static DATA_BLOCK_ADC_TEMPERATURE_s adc_tableTemperature
Definition: adc.c:138
static uint16_t adc_rxReadSingleMessage[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:114
static uint16_t adc_txWriteRegisterCommand[SINGLE_MESSAGE_LENGTH]
Definition: adc.c:107
static STD_RETURN_TYPE_e ADC_Transmit(uint32 blocksize, uint16 *pTxBuffer, uint16 *pRxBuffer, SPI_INTERFACE_CONFIG_s *pSpiInterface)
Definition: adc.c:167
Headers for the driver for the ADC module.
#define ADC_NUMBER_OF_CHANNELS
Definition: adc.h:87
#define ADC_GAIN
Definition: adc.h:77
#define ADC_HET1_RESET_PIN
Definition: adc.h:70
#define ADC_HET1_GIO
Definition: adc.h:68
@ ADC_CONVERT_2
Definition: adc.h:104
@ ADC_LOCK
Definition: adc.h:102
@ ADC_ENDINIT
Definition: adc.h:94
@ ADC_WAKEUP
Definition: adc.h:101
@ ADC_READ_ADC_ENA
Definition: adc.h:99
@ ADC_CHECK_ADC_ENA
Definition: adc.h:100
@ ADC_UNLOCK
Definition: adc.h:96
@ ADC_CONVERT_1
Definition: adc.h:103
@ ADC_READY
Definition: adc.h:95
@ ADC_UNLOCKED
Definition: adc.h:97
@ ADC_WRITE_ADC_ENA
Definition: adc.h:98
@ ADC_INIT
Definition: adc.h:93
#define ADC_VREF_1
Definition: adc.h:73
#define SINGLE_MESSAGE_LENGTH
Definition: adc.h:83
#define ADC_VREF_2
Definition: adc.h:75
#define CONVERT_LENGTH
Definition: adc.h:85
#define BS_NR_OF_TEMP_SENSORS_ON_ADC0
#define BS_NR_OF_TEMP_SENSORS_ON_ADC1
int16_t BETA_GetTemperatureFromBeta(uint16_t adcVoltage_mV)
returns temperature based on measured ADC voltage
Definition: beta.c:95
Resistive divider used for measuring temperature.
Database module header.
#define DATA_READ_DATA(...)
Definition: database.h:76
#define DATA_WRITE_DATA(...)
Definition: database.h:86
@ DATA_BLOCK_ID_ADC_TEMPERATURE
Definition: database_cfg.h:101
int16_t TS_Epc00GetTemperatureFromLut(uint16_t adcVoltage_mV)
returns temperature based on measured ADC voltage
Resistive divider used for measuring temperature.
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:233
#define FAS_TRAP
Define that evaluates to essential boolean false thus tripping an assert.
Definition: fassert.h:108
#define NULL_PTR
Null pointer.
Definition: fstd_types.h:66
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
void IO_PinSet(volatile uint32_t *pRegisterAddress, uint32_t pin)
Set pin by writing in pin output register.
Definition: io.c:70
void IO_PinReset(volatile uint32_t *pRegisterAddress, uint32_t pin)
Set pin by writing in pin output register.
Definition: io.c:77
Header for the driver for the IO module.
STD_RETURN_TYPE_e SPI_TransmitReceiveData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint16 *pTxBuff, uint16 *pRxBuff, uint32 frameLength)
Transmits and receives data on SPI without DMA.
Definition: spi.c:142
Headers for the driver for the SPI module.
SPI_INTERFACE_CONFIG_s spi_adc0Interface
Definition: spi_cfg.c:190
SPI_INTERFACE_CONFIG_s spi_adc1Interface
Definition: spi_cfg.c:199
DATA_BLOCK_ID_e uniqueId
Definition: database_cfg.h:110
int16_t temperatureAdc1_ddegC[BS_NR_OF_TEMP_SENSORS_ON_ADC1]
Definition: database_cfg.h:151
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:149
int16_t temperatureAdc0_ddegC[BS_NR_OF_TEMP_SENSORS_ON_ADC0]
Definition: database_cfg.h:150