==============================================================================
##### How to use this driver #####
==============================================================================
[..]
The I2C HAL driver can be used as follows:
(#) Declare a I2C_HandleTypeDef handle structure, for example:
I2C_HandleTypeDef hi2c;
(#)Initialize the I2C low level resources by implement the HAL_I2C_MspInit() API:
(##) Enable the I2Cx interface clock
(##) I2C pins configuration
(+++) Enable the clock for the I2C GPIOs
(+++) Configure I2C pins as alternate function open-drain
(##) NVIC configuration if you need to use interrupt process
(+++) Configure the I2Cx interrupt priority
(+++) Enable the NVIC I2C IRQ Channel
(##) DMA Configuration if you need to use DMA process
(+++) Declare a DMA_HandleTypeDef handle structure for the transmit or receive stream
(+++) Enable the DMAx interface clock using
(+++) Configure the DMA handle parameters
(+++) Configure the DMA Tx or Rx Stream
(+++) Associate the initialized DMA handle to the hi2c DMA Tx or Rx handle
(+++) Configure the priority and enable the NVIC for the transfer complete interrupt on
the DMA Tx or Rx Stream
(#) Configure the Communication Speed, Duty cycle, Addressing mode, Own Address1,
Dual Addressing mode, Own Address2, General call and Nostretch mode in the hi2c Init structure.
(#) Initialize the I2C registers by calling the HAL_I2C_Init(), configures also the low level Hardware
(GPIO, CLOCK, NVIC...etc) by calling the customized HAL_I2C_MspInit(&hi2c) API.
(#) To check if target device is ready for communication, use the function HAL_I2C_IsDeviceReady()
(#) For I2C IO and IO MEM operations, three operation modes are available within this driver :
*** Polling mode IO operation ***
=================================
[..]
(+) Transmit in master mode an amount of data in blocking mode using HAL_I2C_Master_Transmit()
(+) Receive in master mode an amount of data in blocking mode using HAL_I2C_Master_Receive()
(+) Transmit in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Transmit()
(+) Receive in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Receive()
*** Polling mode IO MEM operation ***
=====================================
[..]
(+) Write an amount of data in blocking mode to a specific memory address using HAL_I2C_Mem_Write()
(+) Read an amount of data in blocking mode from a specific memory address using HAL_I2C_Mem_Read()
*** Interrupt mode IO operation ***
===================================
[..]
(+) Transmit in master mode an amount of data in non blocking mode using HAL_I2C_Master_Transmit_IT()
(+) At transmission end of transfer HAL_I2C_MasterTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterTxCpltCallback
(+) Receive in master mode an amount of data in non blocking mode using HAL_I2C_Master_Receive_IT()
(+) At reception end of transfer HAL_I2C_MasterRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterRxCpltCallback
(+) Transmit in slave mode an amount of data in non blocking mode using HAL_I2C_Slave_Transmit_IT()
(+) At transmission end of transfer HAL_I2C_SlaveTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveTxCpltCallback
(+) Receive in slave mode an amount of data in non blocking mode using HAL_I2C_Slave_Receive_IT()
(+) At reception end of transfer HAL_I2C_SlaveRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** Interrupt mode IO sequential operation ***
==============================================
[..]
(+@) These interfaces allow to manage a sequential transfer with a repeated start condition
when a direction change during transfer
(+) A specific option manage the different steps of a sequential transfer
(+) Differents steps option I2C_XferOptions_definition are listed below :
(++) I2C_FIRST_AND_LAST_FRAME: No sequential usage, functionnal is same as associated interfaces in no sequential mode
(++) I2C_FIRST_FRAME: Sequential usage, this option allow to manage a start condition with data to transfer without a final stop condition
(++) I2C_NEXT_FRAME: Sequential usage, this option allow to manage a restart condition with new data to transfer if the direction change or
manage only the new data to transfer if no direction change and without a final stop condition in both cases
(++) I2C_LAST_FRAME: Sequential usage, this option allow to manage a restart condition with new data to transfer if the direction change or
manage only the new data to transfer if no direction change and with a final stop condition in both cases
(+) Sequential transmit in master I2C mode an amount of data in non-blocking mode using HAL_I2C_Master_Sequential_Transmit_IT()
(++) At transmission end of current frame transfer, HAL_I2C_MasterTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterTxCpltCallback()
(+) Sequential receive in master I2C mode an amount of data in non-blocking mode using HAL_I2C_Master_Sequential_Receive_IT()
(++) At reception end of current frame transfer, HAL_I2C_MasterRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterRxCpltCallback()
(+) Abort a master I2C process communication with Interrupt using HAL_I2C_Master_Abort_IT()
(++) The associated previous transfer callback is called at the end of abort process
(++) mean HAL_I2C_MasterTxCpltCallback() in case of previous state was master transmit
(++) mean HAL_I2c_MasterRxCpltCallback() in case of previous state was master receive
(+) Enable/disable the Address listen mode in slave I2C mode
using HAL_I2C_EnableListen_IT() HAL_I2C_DisableListen_IT()
(++) When address slave I2C match, HAL_I2C_AddrCallback() is executed and user can
add his own code to check the Address Match Code and the transmission direction request by master (Write/Read).
(++) At Listen mode end HAL_I2C_ListenCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_ListenCpltCallback()
(+) Sequential transmit in slave I2C mode an amount of data in non-blocking mode using HAL_I2C_Slave_Sequential_Transmit_IT()
(++) At transmission end of current frame transfer, HAL_I2C_SlaveTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveTxCpltCallback()
(+) Sequential receive in slave I2C mode an amount of data in non-blocking mode using HAL_I2C_Slave_Sequential_Receive_IT()
(++) At reception end of current frame transfer, HAL_I2C_SlaveRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback()
*** Interrupt mode IO MEM operation ***
=======================================
[..]
(+) Write an amount of data in no-blocking mode with Interrupt to a specific memory address using
HAL_I2C_Mem_Write_IT()
(+) At MEM end of write transfer HAL_I2C_MemTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemTxCpltCallback
(+) Read an amount of data in no-blocking mode with Interrupt from a specific memory address using
HAL_I2C_Mem_Read_IT()
(+) At MEM end of read transfer HAL_I2C_MemRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** DMA mode IO operation ***
==============================
[..]
(+) Transmit in master mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Master_Transmit_DMA()
(+) At transmission end of transfer HAL_I2C_MasterTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterTxCpltCallback
(+) Receive in master mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Master_Receive_DMA()
(+) At reception end of transfer HAL_I2C_MasterRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterRxCpltCallback
(+) Transmit in slave mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Slave_Transmit_DMA()
(+) At transmission end of transfer HAL_I2C_SlaveTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveTxCpltCallback
(+) Receive in slave mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Slave_Receive_DMA()
(+) At reception end of transfer HAL_I2C_SlaveRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** DMA mode IO MEM operation ***
=================================
[..]
(+) Write an amount of data in no-blocking mode with DMA to a specific memory address using
HAL_I2C_Mem_Write_DMA()
(+) At MEM end of write transfer HAL_I2C_MemTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemTxCpltCallback
(+) Read an amount of data in no-blocking mode with DMA from a specific memory address using
HAL_I2C_Mem_Read_DMA()
(+) At MEM end of read transfer HAL_I2C_MemRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** I2C HAL driver macros list ***
==================================
[..]
Below the list of most used macros in I2C HAL driver.
(+) __HAL_I2C_ENABLE: Enable the I2C peripheral
(+) __HAL_I2C_DISABLE: Disable the I2C peripheral
(+) __HAL_I2C_GET_FLAG: Checks whether the specified I2C flag is set or not
(+) __HAL_I2C_CLEAR_FLAG: Clear the specified I2C pending flag
(+) __HAL_I2C_ENABLE_IT: Enable the specified I2C interrupt
(+) __HAL_I2C_DISABLE_IT: Disable the specified I2C interrupt
[..]
(@) You can refer to the I2C HAL driver header file for more useful macros
@endverbatim
******************************************************************************
* @attention
*
* <h2><center>© COPYRIGHT(c) 2016 STMicroelectronics</center></h2>
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
* 3. Neither the name of STMicroelectronics nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
******************************************************************************
*/
##### How to use this driver #####
==============================================================================
[..]
The I2C HAL driver can be used as follows:
(#) Declare a I2C_HandleTypeDef handle structure, for example:
I2C_HandleTypeDef hi2c;
(#)Initialize the I2C low level resources by implement the HAL_I2C_MspInit() API:
(##) Enable the I2Cx interface clock
(##) I2C pins configuration
(+++) Enable the clock for the I2C GPIOs
(+++) Configure I2C pins as alternate function open-drain
(##) NVIC configuration if you need to use interrupt process
(+++) Configure the I2Cx interrupt priority
(+++) Enable the NVIC I2C IRQ Channel
(##) DMA Configuration if you need to use DMA process
(+++) Declare a DMA_HandleTypeDef handle structure for the transmit or receive stream
(+++) Enable the DMAx interface clock using
(+++) Configure the DMA handle parameters
(+++) Configure the DMA Tx or Rx Stream
(+++) Associate the initialized DMA handle to the hi2c DMA Tx or Rx handle
(+++) Configure the priority and enable the NVIC for the transfer complete interrupt on
the DMA Tx or Rx Stream
(#) Configure the Communication Speed, Duty cycle, Addressing mode, Own Address1,
Dual Addressing mode, Own Address2, General call and Nostretch mode in the hi2c Init structure.
(#) Initialize the I2C registers by calling the HAL_I2C_Init(), configures also the low level Hardware
(GPIO, CLOCK, NVIC...etc) by calling the customized HAL_I2C_MspInit(&hi2c) API.
(#) To check if target device is ready for communication, use the function HAL_I2C_IsDeviceReady()
(#) For I2C IO and IO MEM operations, three operation modes are available within this driver :
*** Polling mode IO operation ***
=================================
[..]
(+) Transmit in master mode an amount of data in blocking mode using HAL_I2C_Master_Transmit()
(+) Receive in master mode an amount of data in blocking mode using HAL_I2C_Master_Receive()
(+) Transmit in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Transmit()
(+) Receive in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Receive()
*** Polling mode IO MEM operation ***
=====================================
[..]
(+) Write an amount of data in blocking mode to a specific memory address using HAL_I2C_Mem_Write()
(+) Read an amount of data in blocking mode from a specific memory address using HAL_I2C_Mem_Read()
*** Interrupt mode IO operation ***
===================================
[..]
(+) Transmit in master mode an amount of data in non blocking mode using HAL_I2C_Master_Transmit_IT()
(+) At transmission end of transfer HAL_I2C_MasterTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterTxCpltCallback
(+) Receive in master mode an amount of data in non blocking mode using HAL_I2C_Master_Receive_IT()
(+) At reception end of transfer HAL_I2C_MasterRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterRxCpltCallback
(+) Transmit in slave mode an amount of data in non blocking mode using HAL_I2C_Slave_Transmit_IT()
(+) At transmission end of transfer HAL_I2C_SlaveTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveTxCpltCallback
(+) Receive in slave mode an amount of data in non blocking mode using HAL_I2C_Slave_Receive_IT()
(+) At reception end of transfer HAL_I2C_SlaveRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** Interrupt mode IO sequential operation ***
==============================================
[..]
(+@) These interfaces allow to manage a sequential transfer with a repeated start condition
when a direction change during transfer
(+) A specific option manage the different steps of a sequential transfer
(+) Differents steps option I2C_XferOptions_definition are listed below :
(++) I2C_FIRST_AND_LAST_FRAME: No sequential usage, functionnal is same as associated interfaces in no sequential mode
(++) I2C_FIRST_FRAME: Sequential usage, this option allow to manage a start condition with data to transfer without a final stop condition
(++) I2C_NEXT_FRAME: Sequential usage, this option allow to manage a restart condition with new data to transfer if the direction change or
manage only the new data to transfer if no direction change and without a final stop condition in both cases
(++) I2C_LAST_FRAME: Sequential usage, this option allow to manage a restart condition with new data to transfer if the direction change or
manage only the new data to transfer if no direction change and with a final stop condition in both cases
(+) Sequential transmit in master I2C mode an amount of data in non-blocking mode using HAL_I2C_Master_Sequential_Transmit_IT()
(++) At transmission end of current frame transfer, HAL_I2C_MasterTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterTxCpltCallback()
(+) Sequential receive in master I2C mode an amount of data in non-blocking mode using HAL_I2C_Master_Sequential_Receive_IT()
(++) At reception end of current frame transfer, HAL_I2C_MasterRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterRxCpltCallback()
(+) Abort a master I2C process communication with Interrupt using HAL_I2C_Master_Abort_IT()
(++) The associated previous transfer callback is called at the end of abort process
(++) mean HAL_I2C_MasterTxCpltCallback() in case of previous state was master transmit
(++) mean HAL_I2c_MasterRxCpltCallback() in case of previous state was master receive
(+) Enable/disable the Address listen mode in slave I2C mode
using HAL_I2C_EnableListen_IT() HAL_I2C_DisableListen_IT()
(++) When address slave I2C match, HAL_I2C_AddrCallback() is executed and user can
add his own code to check the Address Match Code and the transmission direction request by master (Write/Read).
(++) At Listen mode end HAL_I2C_ListenCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_ListenCpltCallback()
(+) Sequential transmit in slave I2C mode an amount of data in non-blocking mode using HAL_I2C_Slave_Sequential_Transmit_IT()
(++) At transmission end of current frame transfer, HAL_I2C_SlaveTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveTxCpltCallback()
(+) Sequential receive in slave I2C mode an amount of data in non-blocking mode using HAL_I2C_Slave_Sequential_Receive_IT()
(++) At reception end of current frame transfer, HAL_I2C_SlaveRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback()
*** Interrupt mode IO MEM operation ***
=======================================
[..]
(+) Write an amount of data in no-blocking mode with Interrupt to a specific memory address using
HAL_I2C_Mem_Write_IT()
(+) At MEM end of write transfer HAL_I2C_MemTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemTxCpltCallback
(+) Read an amount of data in no-blocking mode with Interrupt from a specific memory address using
HAL_I2C_Mem_Read_IT()
(+) At MEM end of read transfer HAL_I2C_MemRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** DMA mode IO operation ***
==============================
[..]
(+) Transmit in master mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Master_Transmit_DMA()
(+) At transmission end of transfer HAL_I2C_MasterTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterTxCpltCallback
(+) Receive in master mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Master_Receive_DMA()
(+) At reception end of transfer HAL_I2C_MasterRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MasterRxCpltCallback
(+) Transmit in slave mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Slave_Transmit_DMA()
(+) At transmission end of transfer HAL_I2C_SlaveTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveTxCpltCallback
(+) Receive in slave mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Slave_Receive_DMA()
(+) At reception end of transfer HAL_I2C_SlaveRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** DMA mode IO MEM operation ***
=================================
[..]
(+) Write an amount of data in no-blocking mode with DMA to a specific memory address using
HAL_I2C_Mem_Write_DMA()
(+) At MEM end of write transfer HAL_I2C_MemTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemTxCpltCallback
(+) Read an amount of data in no-blocking mode with DMA from a specific memory address using
HAL_I2C_Mem_Read_DMA()
(+) At MEM end of read transfer HAL_I2C_MemRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemRxCpltCallback
(+) In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback
*** I2C HAL driver macros list ***
==================================
[..]
Below the list of most used macros in I2C HAL driver.
(+) __HAL_I2C_ENABLE: Enable the I2C peripheral
(+) __HAL_I2C_DISABLE: Disable the I2C peripheral
(+) __HAL_I2C_GET_FLAG: Checks whether the specified I2C flag is set or not
(+) __HAL_I2C_CLEAR_FLAG: Clear the specified I2C pending flag
(+) __HAL_I2C_ENABLE_IT: Enable the specified I2C interrupt
(+) __HAL_I2C_DISABLE_IT: Disable the specified I2C interrupt
[..]
(@) You can refer to the I2C HAL driver header file for more useful macros
@endverbatim
******************************************************************************
* @attention
*
* <h2><center>© COPYRIGHT(c) 2016 STMicroelectronics</center></h2>
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
* 3. Neither the name of STMicroelectronics nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
******************************************************************************
*/
Комментариев нет:
Отправить комментарий