/**
  @page COMP_Hygrometer Hygrometer example
  
  @verbatim
  ******************** (C) COPYRIGHT 2016 STMicroelectronics *******************
  * @file    COMP/COMP_Hygrometer/readme.txt 
  * @author  MCD Application Team
  * @brief   Description of the hygrometer Example
  ******************************************************************************
  * @attention
  *
  * <h2><center>&copy; Copyright (c) 2016 STMicroelectronics.
  * All rights reserved.</center></h2>
  *
  * This software component is licensed by ST under BSD 3-Clause license,
  * the "License"; You may not use this file except in compliance with the
  * License. You may obtain a copy of the License at:
  *                        opensource.org/licenses/BSD-3-Clause
  *
  ******************************************************************************
  @endverbatim

@par Example Description 

How to make a hygrometer using the capacitive humidity sensor. The capacitance
measurement is performed by continuously charging/discharging the humidity sensor
and measuring the associated time constant.

The voltage of the sensor obeys to the following expression:
  Uc(t)= Vdd*(1-exp-t/(R*C))

Here below how the used peripherals are configured:
  - COMP4 is configured as following:
     - Inverting input is connected to DAC1
     - Non Inverting input is connected to Humidity sensor voltage (PB0)
     - Output is internally connected to TIM4 IC2 (Input Capture channel2)

  - TIM3CLK and TIM4CLK are set to 72 MHz, the prescaler is equal to 0 so the
    counter clock is 72 MHz.

  - TIM3 channel 3 (PC8) is configured in PWM2 mode with duty cycle = 50 %.

  - TIM4 channel 2 is configured in input capture to measure to time constant.  

  - DAC1 is used to generate 2.085V VREF for COMP4


Charging/discharging the capacitance is done by a square signal generated by
TIM3 channel 3 (PC8) and the charge/discharge curve is connected to COMP4 non-inverting
input (PB0). COMP4 output is internally connected to TIM4 IC2 to capture the time
constant. DAC1 is used to define the threshold of COMP4 inverting input

At the moment where COMP4 non-inverting crosses the DAC1 level the formula for
computing the capacitance value is: 
TriggerTime = RES * Capacitance * ln(VDD/(VDD - VREF))
where:
    - TriggerTime is the time when the capture event occurred
    - RES is the charge resistance. It's value is 82.5K 1%
    - Capacitance is the capacitance value of the humidity sensor
    - VDD is the device power supply. It is equal to 3.3V 
    - VREF is the threshold generated by the DAC1
    
@VREF = 2.086V (generated by DAC),  ln(VDD/(VDD - VREF)) is ~ 1
so TriggerTime = RES * Capacitance ==>  Capacitance = TriggerTime/RES 
by consequent Capacitance = (ICReadValue/SystemCoreClock)/RES
where ICReadValue is the captured TIM4 counter and SystemCoreClock is the 
frequency at which the device (specifically TIM3 and TIM4) is running.
Once the capacitance is computed the humidity value is given by: 
RH (%) = -3.4656*10^3 * X^3 + 1.0732*10^4 * X^2 - 1.0457*10^4*X + 3.2459*10^3
with X = Capacitance/Capacitance55RH where Capacitance55RH is capacitance at 55%. 
According to sensor's datasheet, Capacitance55RH has a nominal value of 180pF, with
a tolerance of +/- 3pF. This value can introduce sensitivity error and that's why
it is really recommended to run the gain calibration phase.

Capacitance measurement is sensitive to PCB, GPIO capacitance, propagation delay, etc. 
That's why an offset-calibration phase is provided using a 180pF 1% capacitor C121
by setting JP19 in REF position.

At startup of the example, the offset-calibration phase is started by requesting
to set JP19 in REF position.
Once done, the example requests to set JP19 in HUM position and to set the current
humidity value (gain calibration phase) using joystick UP and DOWN.
This phase can be canceled by pushing KEY button but displayed humidity value is not guaranteed.

@note Care must be taken when using HAL_Delay(), this function provides accurate delay (in milliseconds)
      based on variable incremented in SysTick ISR. This implies that if HAL_Delay() is called from
      a peripheral ISR process, then the SysTick interrupt must have higher priority (numerically lower)
      than the peripheral interrupt. Otherwise the caller ISR process will be blocked.
      To change the SysTick interrupt priority you have to use HAL_NVIC_SetPriority() function.

@note The application need to ensure that the SysTick time base is always set to 1 millisecond
      to have correct HAL operation.

@par Directory contents 

  - COMP/COMP_Hygrometer/Inc/stm32f3xx_hal_conf.h    HAL configuration file
  - COMP/COMP_Hygrometer/Inc/stm32f3xx_it.h      COMP interrupt handlers header file
  - COMP/COMP_Hygrometer/Inc/main.h              Header for main.c module
  - COMP/COMP_Hygrometer/Src/stm32f3xx_it.c      COMP interrupt handlers
  - COMP/COMP_Hygrometer/Src/main.c              Main program
  - COMP/COMP_Hygrometer/Src/system_stm32f3xx.c  STM32F3xx system source file
  - COMP/COMP_Hygrometer/Src/stm32f3xx_hal_msp.c     HAL MSP file


@par Hardware and Software environment

  - This example runs on STM32F3xxx devices.
    
  - This example has been tested with STM32303C-EVAL RevB evaluation board and can be
    easily tailored to any other supported device and development board.    

  - STM32303C-EVAL Set-up
    - Use charge resistor R159 (82.5K 1%) connected to PC8
    - Use the HS1101 humidity sensor connected to PB0
    - Follow example instructions on jumper JP19 position 

@par How to use it ? 

In order to make the program work, you must do the following :
 - Open your preferred toolchain 
 - Rebuild all files and load your image into target memory
 - Run the example

 * <h3><center>&copy; COPYRIGHT STMicroelectronics</center></h3>
 */
