/**
  @page TwoBoards_Example TwoBoards_Example
  
  @verbatim
  ******************** (C) COPYRIGHT 2011 STMicroelectronics *******************
  * @file    Project/STM32_CPAL_Examples/STM32_CPAL_I2C/Two_Boards/readme.txt 
  * @author  MCD Application Team
  * @version V1.1.0
  * @date    17-June-2011
  * @brief   Description of the CPAL Two Boards communication example.
  ******************************************************************************
  * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS
  * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE
  * TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY
  * DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING
  * FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE
  * CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.
  ******************************************************************************
   @endverbatim

@par Example Description 

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

** Hardware Description :

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_______|____|__________|    |         |
|        |                    |                 |                    |         |
|        |                    |                 |                    |         |
|        |  Tamper      Key   |                 |  Tamper      Key   |         |
|        |   _           _    |                 |   _           _    |         |
|        |  |_|         |_|   |                 |  |_|         |_|   |         |
|        |                    |                 |                    |         |
|        |             GND O--|-----------------|--O GND             |         |
|        |____________________|                 |____________________|         |
|                                                                              |
|                                                                              |
*------------------------------------------------------------------------------*

** Software Description :

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 Key is pressed Board A send specific message (tSignal1) to Board B and set 
   the period of Timer to 1.5 seconds. When Tamper is pressed specific message (tSignal2)
   is sent and the period of Timer is set to 0.375 seconds.
Note: When using this example with STM32L152-EVAL Key button is replaced by Joystick-Right
and Tamper button by Joystick-Left.

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 remove the Evaluation board
      I2C SCL jumper if it exist (ie. JP09 on the STM3210C-EVAL evaluation board)
      or 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 
  
  - Two_Boards/system_stm32xxxx.c   STM32xxxx devices system source file (xxxx can be : f10x or l1xx)
  - Two_Boards/stm32xxxx_conf.h     Library Configuration file for STM32xxxx devices (xxxx can be : f10x or l1xx)
  - Two_Boards/stm32_it.c           Interrupt handlers 
  - Two_Boards/stm32_it.h           Interrupt handlers header file 
  - Two_Boards/main.c               Main program
  - Two_Boards/main.h               Header file for main.c    
  - Two_Boards/cpal_conf.h          CPAL Library Configuration file
  - Two_Boards/cpal_usercallback.c  CPAL Usercallbacks definition


@par Hardware and Software environment 

The same example should be loaded in two evaluation boards.

Then these two boards should be connected as follows:
 - Connect I2Cx SCL pin to I2Cx SCL pin
 - Connect I2Cx SDA pin to I2Cx SDA pin
 - Connect Gnd pins of two boards.  

  - This example runs on STM32F10x Connectivity line, High-Density, Medium-Density, 
    XL-Density, Medium-Density Value line, Low-Density, Low-Density Value line Devices,
    STM32L1xx Ultra Low Power Medium-Density Devices and STM32F2xx Devices. 
  
  - This example has been tested with STMicroelectronics STM3210C-EVAL RevB
    (Connectivity line), STM32100E-EVAL RevB (High-Density Value line), 
    STM32L152-EVAL RevB (Ultra Low Power Medium-Density) and STM322xG-EVAL RevB
    evaluation boards and can be easily tailored to any other supported device
    and development board.

  - STM3210C-EVAL Set-up 
    - Connect the two devices as follows:
       - Connect I2C1 SCL pins together (PB6).
       - Connect I2C1 SDA pins together (PB7).
       - Connect at least two Gnd pins.
    - Check that a pull-up resistor is connected on one I2C SDA pin
    - Check that a pull-up resistor is connected on one I2C SCL pin
     Note: on STM3210C-EVAL evaluation board, no need to add pull-up resistor 
     since pull ups are already connected on I2C1 SDA and SCL pins on this board.
    - Make sure the Jumper JP17 "I2C_SCK" is NOT fitted on the two boards.
    - No additional Hardware connections are needed.
     
  - STM32100E-EVAL Set-up 
    - Connect the two devices as follows:
       - Connect I2C2 SCL pins together (PB10).
       - Connect I2C2 SDA pins together (PB11).
       - Connect at least two Gnd pins.
    - Check that a pull-up resistor is connected on one I2C SDA pin
    - Check that a pull-up resistor is connected on one I2C SCL pin
     Note: on STM32100E-EVAL evaluation board, no need to add pull-up resistor 
     since pull ups are already connected on I2C2 SDA and SCL pins on this board.
    - No additional Hardware connections are needed.  
    
  - STM32L152-EVAL Set-up
    - Connect the two devices as follows:
       - Connect I2C1 SCL pins together (PB6).
       - Connect I2C1 SDA pins together (PB7).
       - Connect at least two Gnd pins.
    - Check that a pull-up resistor is connected on one I2C SDA pin
    - Check that a pull-up resistor is connected on one I2C SCL pin
     Note: on STM32L152-EVAL evaluation board, no need to add pull-up resistor 
     since pull ups are already connected on I2C1 SDA and SCL pins on this board.
    - No additional Hardware connections are needed.  

  - STM322xG-EVAL Set-up 
    - Connect the two devices as follows:
       - Connect I2C2 SCL pins together (PB6).
       - Connect I2C2 SDA pins together (PB9).
       - Connect at least two Gnd pins.
    - Check that a pull-up resistor is connected on one I2C SDA pin
    - Check that a pull-up resistor is connected on one I2C SCL pin
     Note: on STM322xG-EVAL evaluation board, no need to add pull-up resistor 
     since pull ups are already connected on I2C1 SDA and SCL pins on this board.
    - No additional Hardware connections are needed.  


@par How to use it ? 
 + EWARM
    - Open the Project.eww workspace.
    - In the workspace toolbar select the project config:
        - STM3210C-EVAL: to configure the project for STM32 Connectivity Line devices.
        - STM32100E-EVAL: to configure the project for STM32 High-Density Value line devices.
        - STM32L152-EVAL: to configure the project for STM32 Ultra Low Power Medium-density devices.
        - STM322xG_EVAL: to configure the project for STM32F2xx devices.
    - Rebuild all files: Project->Rebuild all
    - Load project image: Project->Debug
    - Run program: Debug->Go(F5)
 + MDK-ARM
    - Open the Project.uvproj workspace.
    - In the workspace toolbar select the project config:
        - STM3210C-EVAL: to configure the project for STM32 Connectivity Line devices.
        - STM32100E-EVAL: to configure the project for STM32 High-Density Value line devices.
        - STM32L152-EVAL: to configure the project for STM32 Ultra Low Power Medium-density devices.
        - STM322xG_EVAL: to configure the project for STM32F2xx devices.
    - Rebuild all files: Project>Rebuild all target files
    - Load project image: Debug->Start/Stop Debug session
    - Run program: Debug->Run(F5)

 + TrueSTUDIO
    - Open the TrueSTUDIO toolchain.
    - Click on File->Switch Workspace->Other and browse to TrueSTUDIO workspace directory.
    - Click on File->Import, select General->'Existing Projects into Workspace'
      and then click "Next". 
    - Browse to the TrueSTUDIO workspace directory and select the project:  
        - STM3210C-EVAL: to configure the project for STM32 Connectivity Line devices.
        - STM32100E-EVAL: to configure the project for STM32 High-Density Value line devices.
        - STM32L152-EVAL: to configure the project for STM32 Ultra Low Power Medium-density devices.
        - STM322xG_EVAL: to configure the project for STM32F2xx devices.
    - Under Windows->Preferences->General->Workspace->Linked Resources, add 
      a variable path named "CurPath" which points to the folder containing
      "Libraries", "Project" and "Utilities" folders.
    - Rebuild all project files: Select the project in the "Project explorer" window
      then click on Project->build project menu.
    - Run program: Select the project in the "Project explorer" window then click 
      Run->Debug (F11)
      
 * <h3><center>&copy; COPYRIGHT 2011 STMicroelectronics</center></h3>
 */
