foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
mxm_1785x_tools.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 mxm_1785x_tools.c
44  * @author foxBMS Team
45  * @date 2020-07-15 (date of creation)
46  * @updated 2021-06-16 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix MXM
49  *
50  * @brief This is a collection of helper functions for the MAX1785x ICs
51  *
52  * @details This collection of helper functions for the MAX1785x ICs helps to
53  * calculate the lsb and msb for register values and similar tasks.
54  *
55  */
56 
57 /*========== Includes =======================================================*/
58 #include "mxm_1785x_tools.h"
59 
60 #include "mxm_register_map.h"
61 
62 /*========== Macros and Definitions =========================================*/
63 
64 /*========== Static Constant and Variable Definitions =======================*/
65 
66 /*========== Extern Constant and Variable Definitions =======================*/
67 
68 /*========== Static Function Prototypes =====================================*/
69 
70 /*========== Static Function Implementations ================================*/
71 
72 /*========== Extern Function Implementations ================================*/
73 extern uint8_t MXM_FirstSetBit(uint16_t bitmask) {
74  uint8_t retval = 0;
75  while (((bitmask >> retval) & 1u) == 0u) {
76  retval++;
77  /* exit if every entry is zero */
78  if (retval >= 16u) {
79  break;
80  }
81  }
82  return retval;
83 }
84 
86  /* bitmasks containing only zeros should return first bit set 16 */
88 
90 
92 
94 
95  return STD_OK;
96 }
97 
98 extern void MXM_Convert(
99  uint8_t lsb,
100  uint8_t msb,
101  uint16_t *pTarget,
102  MXM_CONVERSION_TYPE_e convType,
103  uint32_t fullScaleReference_mV) {
104  uint16_t temporaryVoltage = 0;
105  MXM_ExtractValueFromRegister(lsb, msb, MXM_REG_ADC_14BIT_VALUE, &temporaryVoltage);
106 
107  temporaryVoltage = temporaryVoltage + 1u;
108 
109  switch (convType) {
111  /* not yet supported */
113  break;
116  *pTarget = (uint16_t)((temporaryVoltage * fullScaleReference_mV) / 0x3FFFu);
117  break;
118  default:
119  /* we should not be here */
121  break;
122  }
123 }
124 
126  uint16_t voltage = 0u;
127  uint8_t msb = 0u;
128  uint8_t lsb = 0u;
130 
131  /* low scale */
132  msb = 0x00u;
133  lsb = 0x00u;
134  voltage = 1;
135  MXM_Convert(lsb, msb, &voltage, conversionType, 5000);
136  FAS_ASSERT(voltage == 0u);
137 
138  /* half scale */
139  msb = 0x80u;
140  lsb = 0x00u;
141  voltage = 0;
142  MXM_Convert(lsb, msb, &voltage, conversionType, 5000);
143  FAS_ASSERT(voltage == 2500u);
144 
145  /* full scale */
146  msb = 0xFFu;
147  lsb = 0xFCu;
148  voltage = 0;
149  MXM_Convert(lsb, msb, &voltage, conversionType, 5000);
150  FAS_ASSERT(voltage == 5000u);
151 
152  return STD_OK;
153 }
154 
155 extern void MXM_ExtractValueFromRegister(uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue) {
156  /* input sanitation */
157  FAS_ASSERT(pValue != NULL_PTR);
158 
159  /* find lowest bit that is 1 in bitmask */
160  uint8_t start = MXM_FirstSetBit(bitmask);
161 
162  /* apply bitmask to LSB and MSB */
163  uint8_t lsbMasked = lsb & ((uint8_t)(bitmask & MXM_BM_LSB));
164  uint16_t msbBitmask = (bitmask & MXM_BM_MSB);
165  uint8_t msbMasked = msb & ((uint8_t)(msbBitmask >> 8u));
166 
167  /* shift LSB into right position and or over into value */
168  *pValue = (uint16_t)0u | (lsbMasked >> start);
169 
170  /* add MSB at right position */
171  *pValue = (((uint16_t)msbMasked << (8u - start)) | *pValue);
172 }
173 
175  uint8_t lsb = 0x00u;
176  uint8_t msb = 0x00u;
177  uint16_t value = 0x00u;
178 
179  lsb = 0x31u;
180  msb = 0x85u;
181  value = 0x00u;
183  FAS_ASSERT(value == 0x853u);
184 
186  FAS_ASSERT(value == 0x01u);
187 
188  lsb = 0xFCu;
189  msb = 0xFFu;
190  value = 0x00u;
192  FAS_ASSERT(value == 0x3FFFu);
193 
194  lsb = 0xFEu;
195  msb = 0x7Fu;
196  value = 0x00u;
198  FAS_ASSERT(value == 0x1FFFu);
199 
200  return STD_OK;
201 }
202 
203 extern void MXM_Unipolar14BitInto16Bit(uint16_t inputValue, uint8_t *lsb, uint8_t *msb) {
204  uint16_t workingCopy = inputValue;
205  /* left shift into 16bit position */
206  workingCopy = workingCopy << 2u;
207 
208  /* bitmask LSB */
209  *lsb = (uint8_t)(workingCopy & MXM_BM_LSB);
210  /* shift MSB into lower byte (workingCopy is 16bit) */
211  *msb = (uint8_t)(workingCopy >> 8u);
212 }
213 
214 extern uint16_t MXM_VoltageIntoUnipolar14Bit(uint16_t voltage_mV, uint16_t fullscaleReference_mV) {
215  uint32_t temporaryVoltage = voltage_mV;
216  /* multiply by the 14bit fullscale */
217  temporaryVoltage = temporaryVoltage * 0x3FFFu;
218  /* return divided by fullscale_reference */
219  return (uint16_t)(temporaryVoltage / fullscaleReference_mV);
220 }
221 
223  const uint16_t moduleNumber,
224  uint8_t *pStringNumber,
225  uint16_t *pModuleNumberInString) {
226  FAS_ASSERT(pStringNumber != NULL_PTR);
227  FAS_ASSERT(pModuleNumberInString != NULL_PTR);
228  /* the module number cannot be higher than the highest module in the daisy-chain */
229  FAS_ASSERT(moduleNumber < MXM_MAXIMUM_NR_OF_MODULES);
230  /* the module number cannot be higher than number of maximum modules in the string */
231  FAS_ASSERT(moduleNumber < (BS_NR_OF_STRINGS * BS_NR_OF_MODULES));
232 
233  /* calculate string number */
234  *pStringNumber = moduleNumber / BS_NR_OF_MODULES;
235  /* calculate module number and handle edge-case BS_NR_OF_MODULES == 1 */
236  if (1u == BS_NR_OF_MODULES) {
237  *pModuleNumberInString = 0u;
238  } else {
239  *pModuleNumberInString = moduleNumber % BS_NR_OF_MODULES;
240  }
241 }
242 
243 /*========== Externalized Static Function Implementations (Unit Test) =======*/
#define BS_NR_OF_STRINGS
#define BS_NR_OF_MODULES
number of modules in battery pack
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:237
#define FAS_TRAP
Define that evaluates to essential boolean false thus tripping an assert.
Definition: fassert.h:108
@ STD_OK
Definition: fstd_types.h:72
#define NULL_PTR
Null pointer.
Definition: fstd_types.h:66
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
#define must_check_return
Allows functions to generate warnings in GCC for unused returns.
Definition: general.h:95
#define MXM_BM_LSB
Monitoring Register LSB.
#define MXM_BM_MSB
Monitoring Register MSB.
#define MXM_BM_NULL
Monitoring Register Null byte.
#define MXM_REG_VERSION_VER
Monitoring Register Version/Silicon Version.
#define MXM_REG_VERSION_MOD
Monitoring Register Version/Model.
#define MXM_REG_ADC_14BIT_VALUE
Monitoring Register 14bit ADC value.
uint8_t MXM_FirstSetBit(uint16_t bitmask)
Find Position of first set bit in bitmask.
void MXM_Unipolar14BitInto16Bit(uint16_t inputValue, uint8_t *lsb, uint8_t *msb)
convert a unipolar 14bit-value and shifts it into the 16bit-format
void MXM_ConvertModuleToString(const uint16_t moduleNumber, uint8_t *pStringNumber, uint16_t *pModuleNumberInString)
Get the string and module number from a global module number.
STD_RETURN_TYPE_e must_check_return MXM_ConvertTest(void)
Test the MXM_Convert()-function.
STD_RETURN_TYPE_e must_check_return MXM_FirstSetBitTest(void)
Test MXM_FirstSetBit().
uint16_t MXM_VoltageIntoUnipolar14Bit(uint16_t voltage_mV, uint16_t fullscaleReference_mV)
convert a voltage value into a unipolar 14bit value
STD_RETURN_TYPE_e must_check_return MXM_ExtractValueFromRegisterTest(void)
Test MXM_ExtractValueFromRegister().
void MXM_Convert(uint8_t lsb, uint8_t msb, uint16_t *pTarget, MXM_CONVERSION_TYPE_e convType, uint32_t fullScaleReference_mV)
Convert a measurement value to a voltage value.
void MXM_ExtractValueFromRegister(uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue)
Extract a value from a single register.
This is a collection of helper functions for the MAX1785x ICs.
@ MXM_CONVERSION_BIPOLAR
@ MXM_CONVERSION_UNIPOLAR
@ MXM_CONVERSION_BLOCK_VOLTAGE
enum MXM_CONVERSION_TYPE MXM_CONVERSION_TYPE_e
#define MXM_MAXIMUM_NR_OF_MODULES
Maximum number of modules.
Register map of the MAX1785x monitoring IC.
uint16_t MXM_REG_BM
Type for register access for monitoring ICs.