foxBMS  1.3.0
The foxBMS Battery Management System API Documentation
can_helper.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 can_helper.h
44  * @author foxBMS Team
45  * @date 2021-04-22 (date of creation)
46  * @updated 2022-05-30 (date of last update)
47  * @version v1.3.0
48  * @ingroup DRIVERS
49  * @prefix CAN
50  *
51  * @brief Headers for the helper functions for the CAN module
52  *
53  *
54  */
55 
56 #ifndef FOXBMS__CAN_HELPER_H_
57 #define FOXBMS__CAN_HELPER_H_
58 
59 /*========== Includes =======================================================*/
60 #include "general.h"
61 
62 #include "can_cfg.h"
63 
64 /*========== Macros and Definitions =========================================*/
65 
66 /** position for CAN byte 0 to 7
67  * @{
68  */
69 #define CAN_BYTE_0_POSITION (0u)
70 #define CAN_BYTE_1_POSITION (1u)
71 #define CAN_BYTE_2_POSITION (2u)
72 #define CAN_BYTE_3_POSITION (3u)
73 #define CAN_BYTE_4_POSITION (4u)
74 #define CAN_BYTE_5_POSITION (5u)
75 #define CAN_BYTE_6_POSITION (6u)
76 #define CAN_BYTE_7_POSITION (7u)
77 /**@}*/
78 
79 /** type definition for fields of a CAN signal */
80 typedef struct {
81  uint8_t bitStart; /*!< start bit of signal in CAN message */
82  uint8_t bitLength; /*!< length bit of signal in CAN message */
83  float factor; /*!< scaling factor applied to data */
84  float offset; /*!< offset applied to data */
85  float min; /*!< minimum allowed value for signal */
86  float max; /*!< maximum allowed value for signal */
88 
89 /*========== Extern Constant and Variable Declarations ======================*/
90 
91 /*========== Extern Function Prototypes =====================================*/
92 
93 /**
94  * @brief Prepare signal data.
95  * This function takes the signal data and
96  * applies factor, applies offset and compares
97  * with signal minimum and maximum values.
98  * @param[in,out] pSignal signal data
99  * @param[in] signalProperties signal properties (factor, offset, min, max)
100  */
101 extern void CAN_TxPrepareSignalData(float *pSignal, CAN_SIGNAL_TYPE_s signalProperties);
102 
103 /**
104  * @brief Convert raw signal data.
105  * This function takes the raw signal data and
106  * applies offset and factor to convert
107  * the raw value.
108  * @param[out] pSignalConverted coverted signal data
109  * @param[in] signalRaw raw signal data
110  * @param[in] signalProperties signal properties (factor, offset, min, max)
111  */
112 extern void CAN_RxConvertRawSignalData(float *pSignalConverted, float signalRaw, CAN_SIGNAL_TYPE_s signalProperties);
113 
114 /**
115  * @brief Puts CAN signal data in a 64-bit variable.
116  * This function is used to compose a 64-bit CAN message.
117  * It takes signal data, signal bit start, signal bit length
118  * and puts the data in the 64-bit variable.
119  * @param[out] pMessage 64-bit variable containing the CAN data
120  * @param[in] bitStart starting bit were the signal data must be put
121  * @param[in] bitLength length of the signal data to be put in CAN message
122  * @param[in] canSignal signal data to be put in message
123  * @param[in] endianness big or little endianness of data
124  */
126  uint64_t *pMessage,
127  uint64_t bitStart,
128  uint8_t bitLength,
129  uint64_t canSignal,
130  CAN_ENDIANNESS_e endianness);
131 
132 /**
133  * @brief Copy CAN data from a 64-bit variable to 8 bytes.
134  * This function is used to copy a 64-bit CAN message to 8 bytes.
135  * @param[in] message 64-bit variable containing the CAN data
136  * @param[out] pCanData 8 bytes where the data is copied
137  * @param[in] endianness big or little endianness of data
138  */
139 extern void CAN_TxSetCanDataWithMessageData(uint64_t message, uint8_t *pCanData, CAN_ENDIANNESS_e endianness);
140 
141 /**
142  * @brief Gets CAN signal data from a 64-bit variable.
143  * This function is used to get signal data from a 64-bit
144  * CAN message.
145  * It takes signal bit start, signal bit length and extract
146  * signal data from the the 64-bit variable.
147  * @param[in] message 64-bit variable containing the CAN data
148  * @param[in] bitStart starting bit were the signal data must be put
149  * @param[in] bitLength length of the signal data to be put in CAN message
150  * @param[out] pCanSignal signal data to be retrieved from message
151  * @param[in] endianness big or little endianness of data
152  */
154  uint64_t message,
155  uint64_t bitStart,
156  uint8_t bitLength,
157  uint64_t *pCanSignal,
158  CAN_ENDIANNESS_e endianness);
159 
160 /**
161  * @brief Copy CAN data from 8 bytes to a 64-bit variable.
162  * @details This function is used to copy data from a 64-bit variable to 8
163  * bytes.
164  * @param[in] pMessage 64-bit where the data is copied
165  * @param[out] kpkCanData 8 bytes containing the data
166  * @param[in] endianness big or little endianness of data
167  */
169  uint64_t *pMessage,
170  const uint8_t *const kpkCanData,
171  CAN_ENDIANNESS_e endianness);
172 
173 /**
174  * @brief Transform a bool to a bit (set if true)
175  * @param[in] input input boolean (true will become 1u)
176  * @returns unsigned integer indicating the state of the input
177  */
178 extern uint8_t CAN_ConvertBooleanToInteger(bool input);
179 
180 /*========== Externalized Static Function Implementations (Unit Test) =======*/
181 
182 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
183 
184 #endif /* FOXBMS__CAN_HELPER_H_ */
Headers for the configuration for the CAN module.
CAN_ENDIANNESS_e
Definition: can_cfg.h:298
void CAN_TxSetMessageDataWithSignalData(uint64_t *pMessage, uint64_t bitStart, uint8_t bitLength, uint64_t canSignal, CAN_ENDIANNESS_e endianness)
Puts CAN signal data in a 64-bit variable. This function is used to compose a 64-bit CAN message....
Definition: can_helper.c:167
void CAN_TxSetCanDataWithMessageData(uint64_t message, uint8_t *pCanData, CAN_ENDIANNESS_e endianness)
Copy CAN data from a 64-bit variable to 8 bytes. This function is used to copy a 64-bit CAN message t...
Definition: can_helper.c:206
void CAN_RxGetMessageDataFromCanData(uint64_t *pMessage, const uint8_t *const kpkCanData, CAN_ENDIANNESS_e endianness)
Copy CAN data from 8 bytes to a 64-bit variable.
Definition: can_helper.c:289
uint8_t CAN_ConvertBooleanToInteger(bool input)
Transform a bool to a bit (set if true)
Definition: can_helper.c:336
void CAN_TxPrepareSignalData(float *pSignal, CAN_SIGNAL_TYPE_s signalProperties)
Prepare signal data. This function takes the signal data and applies factor, applies offset and compa...
Definition: can_helper.c:142
void CAN_RxConvertRawSignalData(float *pSignalConverted, float signalRaw, CAN_SIGNAL_TYPE_s signalProperties)
Convert raw signal data. This function takes the raw signal data and applies offset and factor to con...
Definition: can_helper.c:161
void CAN_RxGetSignalDataFromMessageData(uint64_t message, uint64_t bitStart, uint8_t bitLength, uint64_t *pCanSignal, CAN_ENDIANNESS_e endianness)
Gets CAN signal data from a 64-bit variable. This function is used to get signal data from a 64-bit C...
Definition: can_helper.c:249
General macros and definitions for the whole platform.
uint8_t bitLength
Definition: can_helper.h:82
uint8_t bitStart
Definition: can_helper.h:81