foxBMS  1.1.2
The foxBMS Battery Management System API Documentation
sbc_fs8x_communication.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016 - 2018, NXP Semiconductors, Inc.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without modification,
6  * are permitted provided that the following conditions are met:
7  *
8  * o Redistributions of source code must retain the above copyright notice, this list
9  * of conditions and the following disclaimer.
10  *
11  * o Redistributions in binary form must reproduce the above copyright notice, this
12  * list of conditions and the following disclaimer in the documentation and/or
13  * other materials provided with the distribution.
14  *
15  * o Neither the name of the copyright holder nor the names of its
16  * contributors may be used to endorse or promote products derived from this
17  * software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 /** @file sbc_fs8x_communication.h
32  * @brief This file contains functions for SPI/I2C communication.
33  *
34  * @author nxf44615
35  * @version 1.1
36  * @date 9-Oct-2018
37  * @copyright Copyright (c) 2016 - 2018, NXP Semiconductors, Inc.
38  *
39  * @updated 2020-03-18 (date of last update)
40  * Adapted driver to pass interface configuration as parameter into the
41  * functions to enable the usage of multiple ICs in the system.
42  */
43 
44 #ifndef SBC_FS8x_COMMUNICATION_H_
45 #define SBC_FS8x_COMMUNICATION_H_
46 
47 /*******************************************************************************
48  * Includes
49  ******************************************************************************/
50 
51 #include <stdint.h>
52 #include <stdbool.h>
53 
54 #include "sbc_fs8x_common.h"
55 
56 /*******************************************************************************
57  * Definitions
58  ******************************************************************************/
59 /* Data frame (SPI or I2C). */
60 #define FS8x_COMM_FRAME_SIZE (0x04U) /*!< Length of the communication frame */
61 
62 /*******************************************************************************
63  * Global Variables
64  ******************************************************************************/
65 
66 /*******************************************************************************
67  * Prototypes of extern functions
68  ******************************************************************************/
69 /** @defgroup Extern MCU specific functions
70  * @brief Functions in this group must be implemented by the user.
71  * @{ */
72 #if FS8x_COMM_TYPE == FS8x_COMM_SPI || FS8x_COMM_TYPE == FS8x_COMM_BOTH
73 /** @brief This function transfers single frame through blocking SPI communication
74  * in both directions. MCU specific.
75  *
76  * This function must be implemented if SPI communication is used. The txFrame must be
77  * sent to the SPI bus from the last byte to the first (e.g. txFrame[0] will be sent
78  * last). The FS8x driver expects incoming data in reversed order, e.g. rxFrame[0] = CRC,
79  * rxFrame[1] = LSB ...
80  * @warning This function must be implemented as blocking as there is not synchronization
81  * mechanism implemented in the driver.
82  * @param [in,out] pSpiInterface SPI communication interface config
83  * @param [in] txFrame Frame to be send.
84  * @param [in] frameLengthBytes Bytes Length of the frame in bytes.
85  * @param [out] rxFrame Received frame.
86  * @return @ref fs8x_status_t "Status return code." */
87 extern fs8x_status_t MCU_SPI_TransferData(SPI_INTERFACE_CONFIG_s* pSpiInterface, uint8_t* txFrame,
88  uint16_t frameLengthBytes, uint8_t* rxFrame);
89 #endif
90 
91 #if FS8x_COMM_TYPE == FS8x_COMM_I2C || FS8x_COMM_TYPE == FS8x_COMM_BOTH
92 /** @brief This function sends single frame to I2C bus.
93  * MCU specific.
94  *
95  * This function must be implemented if I2C communication is used. The txFrame must be
96  * sent to the I2C bus from the last byte to the first (e.g. txFrame[0] will be sent
97  * last).
98  * @warning This function must be implemented as blocking as there is not synchronization
99  * mechanism implemented in the driver.
100  * @param [in] txFrame Frame to be send.
101  * @param [in] frameLengthBytes Frame size in bytes.
102  * @param [in] i2cAddress 7-bit I2C address of the FS8x device.
103  * @return @ref fs8x_status_t "Status return code." */
104 extern fs8x_status_t MCU_I2C_SendData(uint8_t* txFrame, uint8_t frameLengthBytes, uint8_t i2cAddress);
105 
106 /** @brief This function receives single frame from I2C bus.
107  * MCU specific.
108  *
109  * This function must be implemented if I2C communication is used. The FS8x driver expects
110  * incoming data in reversed order, e.g. rxFrame[0] = CRC, rxFrame[1] = LSB ...
111  * @warning This function must be implemented as blocking as there is not synchronization
112  * mechanism implemented in the driver.
113  * @param [in] frameLengthBytes Frame size in bytes.
114  * @param [in] i2cAddress 7-bit I2C address of the FS8x device.
115  * @param [out] rxFrame Received frame.
116  * @return @ref fs8x_status_t "Status return code." */
117 extern fs8x_status_t MCU_I2C_ReceiveData(uint8_t frameLengthBytes, uint8_t i2cAddress, uint8_t* rxFrame);
118 #endif
119 /** @} */
120 /*******************************************************************************
121  * API
122  ******************************************************************************/
123 /** @addtogroup API
124  * @{ */
125 /** @brief Performs a read from a single FS8x register.
126  *
127  * Performs a single read register based on provided address.
128  * The response is returned in @ref fs8x_rx_frame_t structure.
129  * @param [in,out] pSpiInterface SPI communication interface config
130  * @param [in] drvData Driver run-time data.
131  * @param [in] isFailSafe true if the register is Fail Safe.
132  * @param [in] address Register address.
133  * @param [out] rxData Structure holding the response from SBC.
134  * @return @ref fs8x_status_t "Status return code." */
135 fs8x_status_t FS8x_ReadRegister(SPI_INTERFACE_CONFIG_s* pSpiInterface, fs8x_drv_data_t* drvData, bool isFailSafe,
136  uint8_t address, fs8x_rx_frame_t* rxData);
137 
138 /** @brief Sends write command to the FS8x.
139  * @param [in,out] pSpiInterface SPI communication interface config
140  * @param [in] drvData Driver run-time data.
141  * @param [in] isFailSafe true: Reading from FS register, false: Reading from Main register.
142  * @param [in] address Register address.
143  * @param [in] writeData Register write value.
144  * @return @ref fs8x_status_t "Status return code." */
145 fs8x_status_t FS8x_WriteRegister(SPI_INTERFACE_CONFIG_s* pSpiInterface, fs8x_drv_data_t* drvData, bool isFailSafe,
146  uint8_t address, uint16_t writeData);
147 
148 /** @brief Performs a write to a single FS8x FS init register (during the INIT_FS phase only).
149  * @param [in,out] pSpiInterface SPI communication interface config
150  * @param [in] drvData Driver run-time data.
151  * @param [in] address Register address.
152  * @param [in] writeData Register write value.
153  * @return @ref fs8x_status_t "Status return code." */
154 fs8x_status_t FS8x_WriteRegisterInit(SPI_INTERFACE_CONFIG_s* pSpiInterface, fs8x_drv_data_t* drvData, uint8_t address,
155  uint16_t writeData);
156 
157 /** @brief Performs update of a single register. It affects bits specified by a bit mask.
158  * @param [in,out] pSpiInterface SPI communication interface config
159  * @param [in] drvData Driver run-time data.
160  * @param [in] isFailSafe true: Reading from FS register, false: Reading from Main register.
161  * @param [in] address Register address.
162  * @param [in] mask Register write mask.
163  * @param [in] writeData Register write value.
164  * @return @ref fs8x_status_t "Status return code." */
165 fs8x_status_t FS8x_UpdateRegister(SPI_INTERFACE_CONFIG_s* pSpiInterface, fs8x_drv_data_t* drvData, bool isFailSafe,
166  uint8_t address, int16_t mask, uint16_t writeData);
167 /** @} */
168 #endif /* SBC_FS8x_COMMUNICATION_H_ */
fs8x_status_t FS8x_UpdateRegister(SPI_INTERFACE_CONFIG_s *pSpiInterface, fs8x_drv_data_t *drvData, bool isFailSafe, uint8_t address, int16_t mask, uint16_t writeData)
Performs update of a single register. It affects bits specified by a bit mask.
fs8x_status_t FS8x_WriteRegisterInit(SPI_INTERFACE_CONFIG_s *pSpiInterface, fs8x_drv_data_t *drvData, uint8_t address, uint16_t writeData)
Performs a write to a single FS8x FS init register (during the INIT_FS phase only).
fs8x_status_t FS8x_WriteRegister(SPI_INTERFACE_CONFIG_s *pSpiInterface, fs8x_drv_data_t *drvData, bool isFailSafe, uint8_t address, uint16_t writeData)
Sends write command to the FS8x.
fs8x_status_t FS8x_ReadRegister(SPI_INTERFACE_CONFIG_s *pSpiInterface, fs8x_drv_data_t *drvData, bool isFailSafe, uint8_t address, fs8x_rx_frame_t *rxData)
Performs a read from a single FS8x register.
fs8x_status_t
Status return codes.
fs8x_status_t MCU_SPI_TransferData(SPI_INTERFACE_CONFIG_s *pSpiInterface, uint8_t *txFrame, uint16_t frameLengthBytes, uint8_t *rxFrame)
This function transfers single frame through blocking SPI communication in both directions....
Definition: nxpfs85xx.c:941
Driver common structures, enums, macros and configuration values.
This data structure is used by the FS8x driver (this is the first parameter of most the FS8x function...
Structure representing received data frame.