stm32f1xx_hal_adc.c File Reference

This file provides firmware functions to manage the following functionalities of the Analog to Digital Convertor (ADC) peripheral: + Initialization and de-initialization functions ++ Initialization and Configuration of ADC + Operation functions ++ Start, stop, get result of conversions of regular group, using 3 possible modes: polling, interruption or DMA. + Control functions ++ Channels configuration on regular group ++ Channels configuration on injected group ++ Analog Watchdog configuration + State functions ++ ADC state machine management ++ Interrupts and flags management Other functions (extended functions) are available in file "stm32f1xx_hal_adc_ex.c". More...

#include "stm32f1xx_hal.h"

Go to the source code of this file.

Defines
#define	ADC_ENABLE_TIMEOUT   2U
#define	ADC_DISABLE_TIMEOUT   2U
#define	ADC_STAB_DELAY_US   1U
#define	ADC_TEMPSENSOR_DELAY_US   10U
Functions
HAL_StatusTypeDef	HAL_ADC_Init (ADC_HandleTypeDef *hadc)
	Initializes the ADC peripheral and regular group according to parameters specified in structure "ADC_InitTypeDef".
HAL_StatusTypeDef	HAL_ADC_DeInit (ADC_HandleTypeDef *hadc)
	Deinitialize the ADC peripheral registers to their default reset values, with deinitialization of the ADC MSP.
__weak void	HAL_ADC_MspInit (ADC_HandleTypeDef *hadc)
	Initializes the ADC MSP.
__weak void	HAL_ADC_MspDeInit (ADC_HandleTypeDef *hadc)
	DeInitializes the ADC MSP.
HAL_StatusTypeDef	HAL_ADC_RegisterCallback (ADC_HandleTypeDef *hadc, HAL_ADC_CallbackIDTypeDef CallbackID, pADC_CallbackTypeDef pCallback)
	Register a User ADC Callback To be used instead of the weak predefined callback.
HAL_StatusTypeDef	HAL_ADC_UnRegisterCallback (ADC_HandleTypeDef *hadc, HAL_ADC_CallbackIDTypeDef CallbackID)
	Unregister a ADC Callback ADC callback is redirected to the weak predefined callback.
HAL_StatusTypeDef	HAL_ADC_Start (ADC_HandleTypeDef *hadc)
	Enables ADC, starts conversion of regular group.
HAL_StatusTypeDef	HAL_ADC_Stop (ADC_HandleTypeDef *hadc)
	Stop ADC conversion of regular group (and injected channels in case of auto_injection mode), disable ADC peripheral.
HAL_StatusTypeDef	HAL_ADC_PollForConversion (ADC_HandleTypeDef *hadc, uint32_t Timeout)
	Wait for regular group conversion to be completed.
HAL_StatusTypeDef	HAL_ADC_PollForEvent (ADC_HandleTypeDef *hadc, uint32_t EventType, uint32_t Timeout)
	Poll for conversion event.
HAL_StatusTypeDef	HAL_ADC_Start_IT (ADC_HandleTypeDef *hadc)
	Enables ADC, starts conversion of regular group with interruption.
HAL_StatusTypeDef	HAL_ADC_Stop_IT (ADC_HandleTypeDef *hadc)
	Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable interrution of end-of-conversion, disable ADC peripheral.
HAL_StatusTypeDef	HAL_ADC_Start_DMA (ADC_HandleTypeDef *hadc, uint32_t *pData, uint32_t Length)
	Enables ADC, starts conversion of regular group and transfers result through DMA.
HAL_StatusTypeDef	HAL_ADC_Stop_DMA (ADC_HandleTypeDef *hadc)
	Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable ADC DMA transfer, disable ADC peripheral.
uint32_t	HAL_ADC_GetValue (ADC_HandleTypeDef *hadc)
	Get ADC regular group conversion result.
void	HAL_ADC_IRQHandler (ADC_HandleTypeDef *hadc)
	Handles ADC interrupt request.
__weak void	HAL_ADC_ConvCpltCallback (ADC_HandleTypeDef *hadc)
	Conversion complete callback in non blocking mode.
__weak void	HAL_ADC_ConvHalfCpltCallback (ADC_HandleTypeDef *hadc)
	Conversion DMA half-transfer callback in non blocking mode.
__weak void	HAL_ADC_LevelOutOfWindowCallback (ADC_HandleTypeDef *hadc)
	Analog watchdog callback in non blocking mode.
__weak void	HAL_ADC_ErrorCallback (ADC_HandleTypeDef *hadc)
	ADC error callback in non blocking mode (ADC conversion with interruption or transfer by DMA)
HAL_StatusTypeDef	HAL_ADC_ConfigChannel (ADC_HandleTypeDef *hadc, ADC_ChannelConfTypeDef *sConfig)
	Configures the the selected channel to be linked to the regular group.
HAL_StatusTypeDef	HAL_ADC_AnalogWDGConfig (ADC_HandleTypeDef *hadc, ADC_AnalogWDGConfTypeDef *AnalogWDGConfig)
	Configures the analog watchdog.
uint32_t	HAL_ADC_GetState (ADC_HandleTypeDef *hadc)
	return the ADC state
uint32_t	HAL_ADC_GetError (ADC_HandleTypeDef *hadc)
	Return the ADC error code.
HAL_StatusTypeDef	ADC_Enable (ADC_HandleTypeDef *hadc)
	Enable the selected ADC.
HAL_StatusTypeDef	ADC_ConversionStop_Disable (ADC_HandleTypeDef *hadc)
	Stop ADC conversion and disable the selected ADC.
void	ADC_DMAConvCplt (DMA_HandleTypeDef *hdma)
	DMA transfer complete callback.
void	ADC_DMAHalfConvCplt (DMA_HandleTypeDef *hdma)
	DMA half transfer complete callback.
void	ADC_DMAError (DMA_HandleTypeDef *hdma)
	DMA error callback.

---

Detailed Description

This file provides firmware functions to manage the following functionalities of the Analog to Digital Convertor (ADC) peripheral: + Initialization and de-initialization functions ++ Initialization and Configuration of ADC + Operation functions ++ Start, stop, get result of conversions of regular group, using 3 possible modes: polling, interruption or DMA. + Control functions ++ Channels configuration on regular group ++ Channels configuration on injected group ++ Analog Watchdog configuration + State functions ++ ADC state machine management ++ Interrupts and flags management Other functions (extended functions) are available in file "stm32f1xx_hal_adc_ex.c".

Author:

MCD Application Team

  ==============================================================================
                     ##### ADC peripheral features #####
  ==============================================================================
  [..]
  (+) 12-bit resolution

  (+) Interrupt generation at the end of regular conversion, end of injected
      conversion, and in case of analog watchdog or overrun events.
  
  (+) Single and continuous conversion modes.
  
  (+) Scan mode for conversion of several channels sequentially.
  
  (+) Data alignment with in-built data coherency.
  
  (+) Programmable sampling time (channel wise)
  
  (+) ADC conversion of regular group and injected group.

  (+) External trigger (timer or EXTI) 
      for both regular and injected groups.

  (+) DMA request generation for transfer of conversions data of regular group.

  (+) Multimode Dual mode (available on devices with 2 ADCs or more).
  
  (+) Configurable DMA data storage in Multimode Dual mode (available on devices
      with 2 DCs or more).
  
  (+) Configurable delay between conversions in Dual interleaved mode (available 
      on devices with 2 DCs or more).
  
  (+) ADC calibration

  (+) ADC supply requirements: 2.4 V to 3.6 V at full speed and down to 1.8 V at 
      slower speed.
  
  (+) ADC input range: from Vref- (connected to Vssa) to Vref+ (connected to 
      Vdda or to an external voltage reference).


                     ##### How to use this driver #####
  ==============================================================================
    [..]

     *** Configuration of top level parameters related to ADC ***
     ============================================================
     [..]

    (#) Enable the ADC interface
      (++) As prerequisite, ADC clock must be configured at RCC top level.
           Caution: On STM32F1, ADC clock frequency max is 14MHz (refer
                    to device datasheet).
                    Therefore, ADC clock prescaler must be configured in 
                    function of ADC clock source frequency to remain below
                    this maximum frequency.
        (++) One clock setting is mandatory:
             ADC clock (core clock, also possibly conversion clock).
             (+++) Example:
                   Into HAL_ADC_MspInit() (recommended code location) or with
                   other device clock parameters configuration:
               (+++) RCC_PeriphCLKInitTypeDef  PeriphClkInit;
               (+++) __ADC1_CLK_ENABLE();
               (+++) PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_ADC;
               (+++) PeriphClkInit.AdcClockSelection = RCC_ADCPCLK2_DIV2;
               (+++) HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit);

    (#) ADC pins configuration
         (++) Enable the clock for the ADC GPIOs
              using macro __HAL_RCC_GPIOx_CLK_ENABLE()
         (++) Configure these ADC pins in analog mode
              using function HAL_GPIO_Init()

    (#) Optionally, in case of usage of ADC with interruptions:
         (++) Configure the NVIC for ADC
              using function HAL_NVIC_EnableIRQ(ADCx_IRQn)
         (++) Insert the ADC interruption handler function HAL_ADC_IRQHandler() 
              into the function of corresponding ADC interruption vector 
              ADCx_IRQHandler().

    (#) Optionally, in case of usage of DMA:
         (++) Configure the DMA (DMA channel, mode normal or circular, ...)
              using function HAL_DMA_Init().
         (++) Configure the NVIC for DMA
              using function HAL_NVIC_EnableIRQ(DMAx_Channelx_IRQn)
         (++) Insert the ADC interruption handler function HAL_ADC_IRQHandler() 
              into the function of corresponding DMA interruption vector 
              DMAx_Channelx_IRQHandler().

     *** Configuration of ADC, groups regular/injected, channels parameters ***
     ==========================================================================
     [..]

    (#) Configure the ADC parameters (resolution, data alignment, ...)
        and regular group parameters (conversion trigger, sequencer, ...)
        using function HAL_ADC_Init().

    (#) Configure the channels for regular group parameters (channel number, 
        channel rank into sequencer, ..., into regular group)
        using function HAL_ADC_ConfigChannel().

    (#) Optionally, configure the injected group parameters (conversion trigger, 
        sequencer, ..., of injected group)
        and the channels for injected group parameters (channel number, 
        channel rank into sequencer, ..., into injected group)
        using function HAL_ADCEx_InjectedConfigChannel().

    (#) Optionally, configure the analog watchdog parameters (channels
        monitored, thresholds, ...)
        using function HAL_ADC_AnalogWDGConfig().

    (#) Optionally, for devices with several ADC instances: configure the 
        multimode parameters
        using function HAL_ADCEx_MultiModeConfigChannel().

     *** Execution of ADC conversions ***
     ====================================
     [..]

    (#) Optionally, perform an automatic ADC calibration to improve the
        conversion accuracy
        using function HAL_ADCEx_Calibration_Start().

    (#) ADC driver can be used among three modes: polling, interruption,
        transfer by DMA.

        (++) ADC conversion by polling:
          (+++) Activate the ADC peripheral and start conversions
                using function HAL_ADC_Start()
          (+++) Wait for ADC conversion completion 
                using function HAL_ADC_PollForConversion()
                (or for injected group: HAL_ADCEx_InjectedPollForConversion() )
          (+++) Retrieve conversion results 
                using function HAL_ADC_GetValue()
                (or for injected group: HAL_ADCEx_InjectedGetValue() )
          (+++) Stop conversion and disable the ADC peripheral 
                using function HAL_ADC_Stop()

        (++) ADC conversion by interruption: 
          (+++) Activate the ADC peripheral and start conversions
                using function HAL_ADC_Start_IT()
          (+++) Wait for ADC conversion completion by call of function
                HAL_ADC_ConvCpltCallback()
                (this function must be implemented in user program)
                (or for injected group: HAL_ADCEx_InjectedConvCpltCallback() )
          (+++) Retrieve conversion results 
                using function HAL_ADC_GetValue()
                (or for injected group: HAL_ADCEx_InjectedGetValue() )
          (+++) Stop conversion and disable the ADC peripheral 
                using function HAL_ADC_Stop_IT()

        (++) ADC conversion with transfer by DMA:
          (+++) Activate the ADC peripheral and start conversions
                using function HAL_ADC_Start_DMA()
          (+++) Wait for ADC conversion completion by call of function
                HAL_ADC_ConvCpltCallback() or HAL_ADC_ConvHalfCpltCallback()
                (these functions must be implemented in user program)
          (+++) Conversion results are automatically transferred by DMA into
                destination variable address.
          (+++) Stop conversion and disable the ADC peripheral 
                using function HAL_ADC_Stop_DMA()

        (++) For devices with several ADCs: ADC multimode conversion 
             with transfer by DMA:
          (+++) Activate the ADC peripheral (slave) and start conversions
                using function HAL_ADC_Start()
          (+++) Activate the ADC peripheral (master) and start conversions
                using function HAL_ADCEx_MultiModeStart_DMA()
          (+++) Wait for ADC conversion completion by call of function
                HAL_ADC_ConvCpltCallback() or HAL_ADC_ConvHalfCpltCallback()
                (these functions must be implemented in user program)
          (+++) Conversion results are automatically transferred by DMA into
                destination variable address.
          (+++) Stop conversion and disable the ADC peripheral (master)
                using function HAL_ADCEx_MultiModeStop_DMA()
          (+++) Stop conversion and disable the ADC peripheral (slave)
                using function HAL_ADC_Stop_IT()

     [..]

    (@) Callback functions must be implemented in user program:
      (+@) HAL_ADC_ErrorCallback()
      (+@) HAL_ADC_LevelOutOfWindowCallback() (callback of analog watchdog)
      (+@) HAL_ADC_ConvCpltCallback()
      (+@) HAL_ADC_ConvHalfCpltCallback
      (+@) HAL_ADCEx_InjectedConvCpltCallback()

     *** Deinitialization of ADC ***
     ============================================================
     [..]

    (#) Disable the ADC interface
      (++) ADC clock can be hard reset and disabled at RCC top level.
        (++) Hard reset of ADC peripherals
             using macro __ADCx_FORCE_RESET(), __ADCx_RELEASE_RESET().
        (++) ADC clock disable
             using the equivalent macro/functions as configuration step.
             (+++) Example:
                   Into HAL_ADC_MspDeInit() (recommended code location) or with
                   other device clock parameters configuration:
               (+++) PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_ADC
               (+++) PeriphClkInit.AdcClockSelection = RCC_ADCPLLCLK2_OFF
               (+++) HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit)

    (#) ADC pins configuration
         (++) Disable the clock for the ADC GPIOs
              using macro __HAL_RCC_GPIOx_CLK_DISABLE()

    (#) Optionally, in case of usage of ADC with interruptions:
         (++) Disable the NVIC for ADC
              using function HAL_NVIC_EnableIRQ(ADCx_IRQn)

    (#) Optionally, in case of usage of DMA:
         (++) Deinitialize the DMA
              using function HAL_DMA_Init().
         (++) Disable the NVIC for DMA
              using function HAL_NVIC_EnableIRQ(DMAx_Channelx_IRQn)

    [..]
    
    *** Callback registration ***
    =============================================
    [..]

     The compilation flag USE_HAL_ADC_REGISTER_CALLBACKS, when set to 1,
     allows the user to configure dynamically the driver callbacks.
     Use Functions @ref HAL_ADC_RegisterCallback()
     to register an interrupt callback.
    [..]

     Function @ref HAL_ADC_RegisterCallback() allows to register following callbacks:
       (+) ConvCpltCallback               : ADC conversion complete callback
       (+) ConvHalfCpltCallback           : ADC conversion DMA half-transfer callback
       (+) LevelOutOfWindowCallback       : ADC analog watchdog 1 callback
       (+) ErrorCallback                  : ADC error callback
       (+) InjectedConvCpltCallback       : ADC group injected conversion complete callback
       (+) MspInitCallback                : ADC Msp Init callback
       (+) MspDeInitCallback              : ADC Msp DeInit callback
     This function takes as parameters the HAL peripheral handle, the Callback ID
     and a pointer to the user callback function.
    [..]

     Use function @ref HAL_ADC_UnRegisterCallback to reset a callback to the default
     weak function.
    [..]

     @ref HAL_ADC_UnRegisterCallback takes as parameters the HAL peripheral handle,
     and the Callback ID.
     This function allows to reset following callbacks:
       (+) ConvCpltCallback               : ADC conversion complete callback
       (+) ConvHalfCpltCallback           : ADC conversion DMA half-transfer callback
       (+) LevelOutOfWindowCallback       : ADC analog watchdog 1 callback
       (+) ErrorCallback                  : ADC error callback
       (+) InjectedConvCpltCallback       : ADC group injected conversion complete callback
       (+) MspInitCallback                : ADC Msp Init callback
       (+) MspDeInitCallback              : ADC Msp DeInit callback
     [..]

     By default, after the @ref HAL_ADC_Init() and when the state is @ref HAL_ADC_STATE_RESET
     all callbacks are set to the corresponding weak functions:
     examples @ref HAL_ADC_ConvCpltCallback(), @ref HAL_ADC_ErrorCallback().
     Exception done for MspInit and MspDeInit functions that are
     reset to the legacy weak functions in the @ref HAL_ADC_Init()/ @ref HAL_ADC_DeInit() only when
     these callbacks are null (not registered beforehand).
    [..]

     If MspInit or MspDeInit are not null, the @ref HAL_ADC_Init()/ @ref HAL_ADC_DeInit()
     keep and use the user MspInit/MspDeInit callbacks (registered beforehand) whatever the state.
     [..]

     Callbacks can be registered/unregistered in @ref HAL_ADC_STATE_READY state only.
     Exception done MspInit/MspDeInit functions that can be registered/unregistered
     in @ref HAL_ADC_STATE_READY or @ref HAL_ADC_STATE_RESET state,
     thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
    [..]

     Then, the user first registers the MspInit/MspDeInit user callbacks
     using @ref HAL_ADC_RegisterCallback() before calling @ref HAL_ADC_DeInit()
     or @ref HAL_ADC_Init() function.
     [..]

     When the compilation flag USE_HAL_ADC_REGISTER_CALLBACKS is set to 0 or
     not defined, the callback registration feature is not available and all callbacks
     are set to the corresponding weak functions.
  
  

Attention:

© Copyright (c) 2016 STMicroelectronics. All rights reserved.

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

Definition in file stm32f1xx_hal_adc.c.