foxBMS  1.0.0
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_ */
sbc_fs8x_common.h
Driver common structures, enums, macros and configuration values.
FS8x_UpdateRegister
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.
Definition: sbc_fs8x_communication.c:461
fs8x_rx_frame_t
Structure representing received data frame.
Definition: sbc_fs8x_common.h:136
fs8x_status_t
fs8x_status_t
Status return codes.
Definition: sbc_fs8x_common.h:92
fs8x_drv_data_t
This data structure is used by the FS8x driver (this is the first parameter of most the FS8x function...
Definition: sbc_fs8x_common.h:152
SPI_INTERFACE_CONFIG
Definition: spi_cfg.h:107
FS8x_ReadRegister
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.
Definition: sbc_fs8x_communication.c:385
MCU_SPI_TransferData
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
FS8x_WriteRegister
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.
Definition: sbc_fs8x_communication.c:412
FS8x_WriteRegisterInit
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).
Definition: sbc_fs8x_communication.c:439