/**
  @page I2C_TwoBoards  I2C Communication Boards Data Exchange using CPAL Library
  
  @verbatim
  ******************** (C) COPYRIGHT 2015 STMicroelectronics *******************
  * @file    I2C/I2C_TwoBoards/readme.txt 
  * @author  MCD Application Team
  * @version V1.1.3
  * @date    15-December-2021
  * @brief   Description of the CPAL Two Boards communication example.
  ******************************************************************************
  *
  * Copyright (c) 2015 STMicroelectronics.
  * All rights reserved.
  *
  * This software is licensed under terms that can be found in the LICENSE file
  * in the root directory of this software component.
  * If no LICENSE file comes with this software, it is provided AS-IS.
  *
  ******************************************************************************
   @endverbatim

@par Example Description 

This example shows how to use the CPAL library to control I2C devices and 
communicate between two different boards.

To use this example, you need to load the same software into two STM32 boards
(let's call them  Board A and Board B) then connect these two boards through I2C
lines and Gnd.

*------------------------------------------------------------------------------*
|                BOARD A                                BOARD B                |
|         ____________________                   ____________________          |
|        |                    |                 |                    |         |
|        |                    |                 |                    |         | 
|        |     __________     |                 |     __________     |         |
|        |    |I2C Device|____|_______SCL_______|____|I2C Device|    |         |
|        |    |__________|____|_______SDA_______|____|__________|    |         |
|        |                    |                 |                    |         |
|        |                    |                 |                    |         |
|        |  LEFT       RIGHT  |                 |  LEFT       RIGHT  |         |
|        |   _           _    |                 |   _           _    |         |
|        |  |_|         |_|   |                 |  |_|         |_|   |         |
|        |                    |                 |                    |         |
|        |             GND O--|-----------------|--O GND             |         |
|        |____________________|                 |____________________|         |
|                                                                              |
|                                                                              |
*------------------------------------------------------------------------------*

The example software perform the following actions:
 - At startup, Boards A & B are both in slave receiver mode and wait for messages 
   to be received.
 - When a push button is pressed, for example on Board A, the master transmitter 
   mode is activated and a message is sent to Board B containing identification 
   of the action relative to the push button.
 - Once a message is correctly sent, Board A activates the master transmitter mode 
   permanently and disables the slave receiver mode.
 - Once a message is received and correctly recognized, Board B activate the
   receiver mode and disable the transmitter mode. (push buttons interrupts are
   still active but message sending is disabled).
 - According to the push button pressed, a value is affected to a Timer which 
   generates periodic high priority interrupts. At each interrupt, a status message
   is sent to Board B. The period of Timer interrupts is variable depending on
   the push button pressed.    
 - When LEFT is pressed Board A send specific message (tSignal1) to Board B and set 
   the period of Timer to 1.5 seconds. When RIGHT is pressed specific message (tSignal2)
   is sent and the period of Timer is set to 0.305 seconds.

For each event (message received, message transmitted, error occur ...) a 
relative information is displayed on the LCD screen. When the same event is 
repeated, the line color is switched to highlight the event occurrence.

the Mode of Board (transmitter or receiver) is monitored by LEDs:
      - LED2 is toggling when transmitter mode is activated.
      - LED3 is toggling when receiver mode is activated. 

LED1 and LED4 are toggling by an interrupt generated by TIM6 each 50ms.

The programming model of I2C communication can be selected (DMA or Interrupt) in 
cpal_conf.h file by commenting or uncommenting these defines in Section 2 (Transfer
Options Configuration):
              #define CPAL_I2C_DMA_PROGMODEL
              #define CPAL_I2C_IT_PROGMODEL
Note : Only one define must selected. If these two defines are uncommented DMA Programming 
model is selected and the code size of this example will increase.

 
** UserCallbacks :

   - CPAL_TIMEOUT_UserCallback : This Callback is called to manage timeout error.
      In this Callback I2C device is reinitialized.
      
   - CPAL_I2C_ERR_UserCallback : This Callback is called to manage Device error .  
      In this Callback I2C device is reinitialized.
      Note: 
      If you want to generate an I2C error, you can disconnect I2C_SCL/I2C_SDA connector.
      In this case the I2C communication will be corrupted and the CPAL I2C error callbacks
      will be entered. If you fit back the jumper or connector, the communication should be 
      recovered immediately thanks to CPAL error management. 
      
   - CPAL_I2C_TXTC_UserCallback : This Callback is called when Write operation 
      is completed. In this Callback only information relative to communication 
      are displayed on LCD screen.
      
   - CPAL_I2C_RXTC_UserCallback : This Callback is called when Read operation 
      is completed. In this Callback received data are compared and transfer 
      status is displayed on LCD screen.
 

@par Directory contents 

  - I2C/I2C_TwoBoards/stm32f30x_conf.h                   Library Configuration file
  - I2C/I2C_TwoBoards/stm32f30x_it.c                     Interrupt handlers
  - I2C/I2C_TwoBoards/stm32f30x_it.h                     Interrupt handlers header file
  - I2C/I2C_TwoBoards/main.c                             Main program
  - I2C/I2C_TwoBoards/main.h                             Main program header file   
  - I2C/I2C_TwoBoards/system_stm32f30x.c                 STM32F30x system source file
  - I2C/I2C_TwoBoards/stm32f30x_i2c_cpal_conf.h          CPAL Library Configuration file
  - I2C/I2C_TwoBoards/stm32f30x_i2c_cpal_usercallback.c  CPAL Usercallbacks definition
  
@note The "system_stm32f30x.c" is generated by an automatic clock configuration 
      system and can be easily customized to your own configuration. 
      To select different clock setup, use the "STM32F30x_Clock_Configuration_V1.0.0.xls" 
      provided with the AN4152 package available on <a href="http://www.st.com/internet/mcu/family/141.jsp">  ST Microcontrollers </a>
        
@par Hardware and Software environment

  - This example runs on STM32F303xC and STM32F303xE Devices.
  
  - This example has been tested with STMicroelectronics STM32303C-EVAL (STM32F30x)
    evaluation board and can be easily tailored to any other supported device 
    and development board. 

 - The same example should be loaded in two evaluation boards.
    
 - STM32303C-EVAL Set-up :
   Then these two boards should be connected as follows:
     - Connect I2C2 SCL pin (PF6) to I2C2 SCL pin (PF6)
     - Connect I2C2 SDA pin (PA10) to I2C2 SDA pin (PA10)
     - Connect Gnd pins of two boards.
    
@par How to use it ? 

In order to make the program work, you must do the following :
 - Copy all source files from this example folder to the template folder under
   Projects\STM32F30x_StdPeriph_Templates
 - Open your preferred toolchain 
 - Add the following files the project source list
     - Libraries\STM32F30x_I2C_CPAL_Driver\src\stm32f30x_i2c_cpal.c
     - Libraries\STM32F30x_I2C_CPAL_Driver\src\stm32f30x_i2c_cpal_hal.c
     - Projects\STM32F30x_StdPeriph_Templates\stm32f30x_i2c_cpal_usercallback.c
     - Utilities\STM32_EVAL\STM32303C_EVAL\stm32303c_eval.c
     - Utilities\STM32_EVAL\STM32303C_EVAL\stm32303c_eval_lcd.c
 - Rebuild all files and load your image into target memory
 - Run the example
    

 */
