PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Enumerations | Functions
ADC (Analog to Digital Converter)
HAL API Reference » HAL Drivers

## General Description

High level interface for interacting with the analog to digital converter (ADC).

# Features

Both single-ended and differential channels are supported. The values returned by the read API are relative to the ADC's voltage range, which is device specific. See the BSP documentation for details.

# Quickstart

1. Initialize the ADC hardware and channels via PDL call
2. Allocate the memory for the HAL ADC object
3. Set up the HAL ADC using mtb_hal_adc_setup by passing the HAL ADC object and the pre-initialized ADC structures.

Note
  mtb_hal_adc_read_u16 always returns a 16 bit value in the range 0x0000-0xFFFF. If the underlying hardware does not support 16 bit resolution the value is scaled linearly to cover the full 16 bits.

# Code snippets

Note
  Error checking is omitted for clarity

## Snippet 1: Simple ADC initialization and reading conversion result

The following snippet initializes an ADC and one channel. One ADC conversion result is returned corresponding to the input at the specified pin.

cy_rslt_t rslt;
mtb_hal_adc_t adc_obj;
mtb_hal_adc_channel_t channel_0, channel_1;
mtb_hal_adc_channel_t* channels[] = { &channel_0, &channel_1 };
int32_t adc_output;
#if defined(CY_IP_MXS40EPASS_ESAR_INSTANCES)
/* IP-specific PDL initialization */
rslt = (cy_rslt_t)Cy_SAR2_Init(ADC_0_HW, &ADC_0_config);
Cy_SAR2_SetReferenceBufferMode(PASS0_EPASS_MMIO, CY_SAR2_REF_BUF_MODE_ON);
#endif /* defined(CY_IP_MXS40EPASS_ESAR_INSTANCES) */
rslt = mtb_hal_adc_setup(&adc_obj, &ADC_0_hal_config, NULL, channels);
// Read the ADC conversion result for corresponding ADC channel. Repeat as necessary.
adc_output = mtb_hal_adc_read_u16(&channel_0);
mtb_hal_adc_setup
cy_rslt_t mtb_hal_adc_setup(mtb_hal_adc_t *obj, const mtb_hal_adc_configurator_t *config, mtb_hal_clock_t *clk, mtb_hal_adc_channel_t **channels)
Sets up a HAL instance to use the specified hardware resource.
mtb_hal_adc_read_u16
uint16_t mtb_hal_adc_read_u16(const mtb_hal_adc_channel_t *obj)
Read the value from the ADC pin, represented as an unsigned 16bit value where 0x0000 represents the m...
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
mtb_hal_adc_channel_t
ADC channel object.
Definition: mtb_hal_hw_types_adc_lppass.h:95
mtb_hal_adc_t
ADC object.
Definition: mtb_hal_hw_types_adc_lppass.h:57

## Snippet 2: Single-channel ADC initialization set to start a fresh conversion and read the latest result.

void snippet_mtb_hal_read_latest(void)
{
mtb_hal_adc_t adc_obj;
mtb_hal_adc_channel_t channel_0;
mtb_hal_adc_channel_t* channels[] = { &channel_0 };
int32_t read_val;
cy_rslt_t rslt;
#if defined(CY_IP_MXS40EPASS_ESAR_INSTANCES)
/* IP-specific PDL initialization */
rslt = (cy_rslt_t)Cy_SAR2_Init(ADC_0_HW, &ADC_0_config);
if (rslt != CY_RSLT_SUCCESS)
{
// Address failure
return;
}
Cy_SAR2_SetReferenceBufferMode(PASS0_EPASS_MMIO, CY_SAR2_REF_BUF_MODE_ON);
#endif /* defined(CY_IP_MXS40EPASS_ESAR_INSTANCES) */
rslt = mtb_hal_adc_setup(&adc_obj, &ADC_0_hal_config, NULL, channels);
if (rslt != CY_RSLT_SUCCESS)
{
// Address failure
return;
}
// Start a new conversion
rslt = mtb_hal_adc_start_convert(&adc_obj);
if (rslt != CY_RSLT_SUCCESS)
{
// Address failure
return;
}
// Wait for the conversion to finish
while (!mtb_hal_adc_is_conversion_complete(&channel_0))
{
}
// Read the conversion result
rslt = mtb_hal_adc_read_latest(&channel_0, &read_val);
if (rslt != CY_RSLT_SUCCESS)
{
// Address failure
return;
}
}
mtb_hal_adc_read_latest
cy_rslt_t mtb_hal_adc_read_latest(const mtb_hal_adc_channel_t *obj, int32_t *result)
Reads the result of the most recent scan for the specified channel and writes it to the given result ...
mtb_hal_adc_start_convert
cy_rslt_t mtb_hal_adc_start_convert(mtb_hal_adc_t *obj)
Triggers start of conversion for all enabled channels.
mtb_hal_adc_is_conversion_complete
bool mtb_hal_adc_is_conversion_complete(const mtb_hal_adc_channel_t *obj)
Returns true if the most recently triggered conversion has completed for the specified channel.
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486

## API Reference
| ADC HAL Results
| ADC specific return codes.

## Enumerations
enum | mtb_hal_adc_filter_t { MTB_HAL_ADC_FILTER_MEDIAN = 0 , MTB_HAL_ADC_FILTER_LIF = 1 , MTB_HAL_ADC_FILTER_AVG = 2 , MTB_HAL_ADC_FILTER_CIC = 3 , MTB_HAL_ADC_FILTER_LPF = 4 }
| Enum of ADC filter types that get applied to the acquired ADC data. More...

## Functions
cy_rslt_t | mtb_hal_adc_setup (mtb_hal_adc_t *obj, const mtb_hal_adc_configurator_t *config, mtb_hal_clock_t *clk, mtb_hal_adc_channel_t **channels)
| Sets up a HAL instance to use the specified hardware resource. More...
uint16_t | mtb_hal_adc_read_u16 (const mtb_hal_adc_channel_t *obj)
| Read the value from the ADC pin, represented as an unsigned 16bit value where 0x0000 represents the minimum value in the ADC's range, and 0xFFFF represents the maximum value in the ADC's range. More...
bool | mtb_hal_adc_is_conversion_complete (const mtb_hal_adc_channel_t *obj)
| Returns true if the most recently triggered conversion has completed for the specified channel. More...
cy_rslt_t | mtb_hal_adc_read_latest (const mtb_hal_adc_channel_t *obj, int32_t *result)
| Reads the result of the most recent scan for the specified channel and writes it to the given `result` location. More...
cy_rslt_t | mtb_hal_adc_read_multiple (mtb_hal_adc_channel_t **channels, uint32_t num_channels, int32_t *result)
| Read the value from the most recent scan for the specified set of ADC channels and writes it to the array specified by result. More...
cy_rslt_t | mtb_hal_adc_start_convert (mtb_hal_adc_t *obj)
| Triggers start of conversion for all enabled channels. More...
cy_rslt_t | mtb_hal_adc_enable (mtb_hal_adc_t *obj, bool enable)
| Enable/disable the ADC. More...
bool | mtb_hal_adc_is_ready (mtb_hal_adc_t *obj)
| Check if ADC is ready to be used. More...
cy_rslt_t | mtb_hal_adc_read_filtered (const mtb_hal_adc_channel_t *obj, mtb_hal_adc_filter_t filter, int32_t *result)
| Reads the filtered result of the most recent scan for the specified channel and writes it to the given `result` location. More...

## Enumeration Type Documentation

## ◆ mtb_hal_adc_filter_t

enum mtb_hal_adc_filter_t

Enum of ADC filter types that get applied to the acquired ADC data.

Enumerator
MTB_HAL_ADC_FILTER_MEDIAN | Median filter.
MTB_HAL_ADC_FILTER_LIF | Linear interpolation filter.
MTB_HAL_ADC_FILTER_AVG | Average filter.
MTB_HAL_ADC_FILTER_CIC | Cascaded integrated comb filter.
MTB_HAL_ADC_FILTER_LPF | Low pass filter.

## Function Documentation

## ◆ mtb_hal_adc_setup()

cy_rslt_t mtb_hal_adc_setup | ( | mtb_hal_adc_t * | obj,
|  | const mtb_hal_adc_configurator_t * | config,
|  | mtb_hal_clock_t * | clk,
|  | mtb_hal_adc_channel_t ** | channels
| ) |  |

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

  [out] | obj | The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
  [in] | config | The configurator-generated HAL config structure for this peripheral instance
  [in] | clk | Clock instance that clocks this peripheral
  [in] | channels | Array of channels used by the ADC. Unused channels should be passed as NULL

Returns
  the status of the HAL setup

## ◆ mtb_hal_adc_read_u16()

uint16_t mtb_hal_adc_read_u16 | ( | const mtb_hal_adc_channel_t * | obj | ) |

Read the value from the ADC pin, represented as an unsigned 16bit value where 0x0000 represents the minimum value in the ADC's range, and 0xFFFF represents the maximum value in the ADC's range.

If continous scanning is disabled, this will block while a conversion is performed on the selected channel, then return the result. Depending on the ADC speed this function may block for some time. If continuous scanning is enabled, this will return the value from the most recent conversion of the specified channel (if called shortly after enabling continuous scanning it may block until at least one conversion has been performed on this channel).

Parameters

  [in] | obj | The ADC object

Returns
  An unsigned 16bit value representing the current input voltage

## ◆ mtb_hal_adc_is_conversion_complete()

bool mtb_hal_adc_is_conversion_complete | ( | const mtb_hal_adc_channel_t * | obj | ) |

Returns true if the most recently triggered conversion has completed for the specified channel.

If continuous conversion is enabled, returns true if at least one conversion has completed.

Parameters

  [in] | obj | The ADC object

Returns
  True if conversion completed, false if still ongoing

## ◆ mtb_hal_adc_read_latest()

cy_rslt_t mtb_hal_adc_read_latest | ( | const mtb_hal_adc_channel_t * | obj,
|  | int32_t * | result
| ) |  |

Reads the result of the most recent scan for the specified channel and writes it to the given `result` location.

This function will return the latest available value.

Parameters

  [in] | obj | The ADC object
  [out] | result | Scanned result

Returns
  The status of the read operation

## ◆ mtb_hal_adc_read_multiple()

cy_rslt_t mtb_hal_adc_read_multiple | ( | mtb_hal_adc_channel_t ** | channels,
|  | uint32_t | num_channels,
|  | int32_t * | result
| ) |  |

Read the value from the most recent scan for the specified set of ADC channels and writes it to the array specified by result.

If a conversion has not completed for one or more of the specified channels, it will return error and will not update value to the array. "channels" and "result" list must have "num_channels" space in order to get ADC channels and store the results respectively.

This function will return the latest available value.

Parameters

  [in] | channels | The ADC channels object pointer
  [in] | num_channels | The number of ADC channels
  [out] | result | Scanned result

Returns
  The status of the read operation

## ◆ mtb_hal_adc_start_convert()

cy_rslt_t mtb_hal_adc_start_convert | ( | mtb_hal_adc_t * | obj | ) |

Triggers start of conversion for all enabled channels.

The function returns without waiting for the conversion to complete.

Parameters

  [in] | obj | The ADC object

Returns
  The status of the conversion request

## ◆ mtb_hal_adc_enable()

cy_rslt_t mtb_hal_adc_enable | ( | mtb_hal_adc_t * | obj,
|  | bool | enable
| ) |  |

Enable/disable the ADC.

The function returns without waiting for the enable to complete. Check the ADC status using mtb_hal_adc_is_ready.

Parameters

  [in] | obj | The ADC object
  [in] | enable | Enable/disable

Returns
  The status of the enable request

## ◆ mtb_hal_adc_is_ready()

bool mtb_hal_adc_is_ready | ( | mtb_hal_adc_t * | obj | ) |

Check if ADC is ready to be used.

Parameters

  [in] | obj | The ADC object

Returns
  The status of the ADC ready state

## ◆ mtb_hal_adc_read_filtered()

cy_rslt_t mtb_hal_adc_read_filtered | ( | const mtb_hal_adc_channel_t * | obj,
|  | mtb_hal_adc_filter_t | filter,
|  | int32_t * | result
| ) |  |

Reads the filtered result of the most recent scan for the specified channel and writes it to the given `result` location.

This function will return the latest available value.

Parameters

  [in] | obj | The ADC object
  [in] | filter | Filter type
  [out] | result | Scanned result

Returns
  The status of the read operation