/**
  @page COMP_Hygrometer Hygrometer example
  
  @verbatim
  ******************** (C) COPYRIGHT 2015 STMicroelectronics *******************
  * @file    COMP/COMP_Hygrometer/readme.txt 
  * @author  MCD Application Team
  * @version V1.1.3
  * @date    15-December-2021
  * @brief   Description of the hygrometer 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 make a hygrometer using the capacitive humidity sensor HS1101.
The capacitance measurement is based on continuously charging/discharging the
humidity sensor and measuring the 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
(by default COMP4 inverting input is connected to the DAC1 and be connected to
Vrefint=1.22V by commenting #define USE_DAC 1 and uncommenting #define USE_VREFINT 1
in main.h)
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.


@par Directory contents 

  - COMP/COMP_Hygrometer/stm32f30x_conf.h    Library Configuration file
  - COMP/COMP_Hygrometer/stm32f30x_it.c      Interrupt handlers
  - COMP/COMP_Hygrometer/stm32f30x_it.h      Interrupt handlers header file
  - COMP/COMP_Hygrometer/main.c              Main program
  - COMP/COMP_Hygrometer/main.h              Main Header file
  - COMP/COMP_Hygrometer/system_stm32f30x.c  STM32F30x system source file

@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 STM32303-EVAL RevB (STM32F30x)
    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 :
 - 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 to the project source list
    - 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
    

 */
