ADC (Analog to Digital Converter)

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);
 

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;
    }
}
 
 

API Reference
	ADC HAL Results
	ADC specific return codes.

Macros
#define	MTB_HAL_ADC_BITS   16
	Number of bits populated with meaningful data by each ADC sample.
#define	MTB_HAL_ADC_MAX_VALUE   ((1 << MTB_HAL_ADC_BITS) - 1)
	Maximum value that the ADC can return.

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...

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