This application note explains how to use the STM32H7 ADC in the FreeRTOS demo application.

1. Understanding ADC Interfaces

1.1. FreeRTOS ADC Implementation

The FreeRTOS BSP makes use of the STM32CubeH7 software component to provide a device driver for the STM32H7 ADC. The driver is configured (enabled / disabled) at the BSP build time, using the HAL_ADC_MODULE_ENABLED configuration option, defined in the stm32h7xx_hal_conf.h file.

1.2. FreeRTOS ADC C-Binding API

The ADC driver implements the following C-binding API:

Function	Description	Comments
`HAL_StatusTypeDef HAL_ADC_Init(ADC_HandleTypeDef * hadc)`
	Initialize the ADC peripheral and regular group according to the specified parameters by `hadc`	`hadc` is a pointer to a structure that contains the configuration information for ADC (ADC handle); returns one of `{HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}`
`HAL_StatusTypeDef HAL_ADC_DeInit(ADC_HandleTypeDef * hadc)`
	Deinitialize the ADC peripheral registers to their default reset values	`hadc` is an ADC handle; returns one of `{HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}`
`HAL_StatusTypeDef HAL_ADC_ConfigChannel(ADC_HandleTypeDef * hadc, ADC_ChannelConfTypeDef * sConfig)`
	Configure a channel to be assigned to ADC group regular	`hadc` is an ADC handle; `sConfig` is a ADC configuration structure; returns one of `{HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}`
`HAL_StatusTypeDef HAL_ADCEx_Calibration_Start((ADC_HandleTypeDef * hadc, uint32_t CalibrationMode, uint32_t SingleDiff)`
	Perform an ADC automatic self-calibration	`hadc` is an ADC handle
`HAL_StatusTypeDef HAL_ADC_Start(ADC_HandleTypeDef * hadc)`
	Enable ADC, starts conversion of regular group	`hadc` is an ADC handle; returns one of `{HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}`
`HAL_StatusTypeDef HAL_ADC_PollForConversion(ADC_HandleTypeDef * hadc, uint32_t Timeout)`
	Wait for regular group conversion to be completed	`hadc` is an ADC handle; returns one of `{HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT}`
`uint32_t HAL_ADC_GetValue(ADC_HandleTypeDef * hadc)`
	Get ADC regular group conversion result	`hadc` is an ADC handle; returns a ADC group regular conversion data

The ADC_HandleTypeDef data structure used in this API has the following definition:

typedef struct
{
  ADC_TypeDef                *Instance;         /* Register base address */
  ADC_InitTypeDef             Init;             /* ADC initialization parameters
                                                   and regular conversions 
                                                   setting */
  DMA_HandleTypeDef           *DMA_Handle;      /* Pointer DMA Handler */
  HAL_LockTypeDef             Lock;             /* ADC locking object */
  __IO uint32_t               State;            /* ADC communication state
                                                  (bit-map of ADC states) */
  __IO uint32_t               ErrorCode;        /* ADC Error code */
  ADC_InjectionConfigTypeDef  InjectionConfig ; /* ADC injected channel 
                                                   configuration build-up 
                                                   structure */
} ADC_HandleTypeDef;

The ADC_InjectionConfigTypeDef data structure used in ADC_HandleTypeDef has the following definition:

typedef struct
{
  uint32_t ContextQueue;      /* Injected channel configuration context */
  uint32_t ChannelCount;      /* Number of channels in the injected sequence */
} ADC_InjectionConfigTypeDef;

The ADC_ChannelConfTypeDef data structure used in HAL_ADC_ConfigChannel interface has the following definition:

typedef struct
{
  uint32_t Channel;                       /* Specify the channel to configure 
                                             into ADC regular group. */
  uint32_t Rank;                          /* Specify the rank in the regular 
                                             group sequencer. */
  uint32_t SamplingTime;                  /* Sampling time value to be set for 
                                             the selected channel. */
  uint32_t SingleDiff;                    /* Select single-ended or differential
                                             input. */
  uint32_t OffsetNumber;                  /* Select the offset number. */
  uint32_t Offset;                        /* Define the offset to be subtracted 
                                             from the raw converted data. */
  FunctionalState OffsetRightShift;       /* Define the Right-shift data 
                                             after Offset correction. */
  FunctionalState OffsetSignedSaturation; /* Specify whether the Signed 
                                             saturation feature is used or not.*/
} ADC_ChannelConfTypeDef;

2. ADC CLI Command

The FreeRTOS application implements the following ADC related CLI command:

Command	Description	Comments
`adc_se<nadc> <chnl>`	Run the ADC test in the single-ended input mode	`nadc` is the ADC number, `chnl` is the channel number

3. Validating ADC Operation

Use the following step-wise procedure to validate the FreeRTOS ADC operation:

Connect a 2.6V voltage to the ADC pin.
- On the STM32H7-BSB Rev 1A board: P4.7 (PA4) pin.
- On the STM32H7-BSB Rev 2A board: P4.4 (PA4) pin.
Power cycle the target board and let it boot to the FreeRTOS CLI.
From the CLI, run the adc_se command:
```
CLI> adc_se 1 18
Input voltage = 2667mV
```
Compare the output result with the input voltage. Make sure the two match.
Change the input voltage to 0.6V.
Run the adc_se command again:
```
CLI> adc_se 1 18
Input voltage = 659mV
```
Compare the output result with the input voltage. Make sure the two match.

Using ADC in FreeRTOS

1. Understanding ADC Interfaces

1.1. FreeRTOS ADC Implementation

1.2. FreeRTOS ADC C-Binding API

2. ADC CLI Command

3. Validating ADC Operation