group group_hal_adc

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

Features

Each ADC instance supports one or more selectable channels, each of which can perform conversions on a different pin. See the device datasheet for details about which pins support ADC conversion.

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

Call cyhal_adc_init to initialize an ADC instance by providing the ADC object (obj), input pin (pin) and clock (clk).

The input pin argument is just to signify which ADC instance to initialize. It does not actually reserve the pin or create an ADC channel for it. The clock parameter can be left NULL to use an available clock resource with a default frequency.

Use

cyhal_adc_channel_init_diff to initialize one or more channels associated with that instance.

Use

See

note

cyhal_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

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;

// Initialize ADC channel, allocate channel number 0 to pin ADC_VPLUS1 as this is the first
// channel initialized
{ .enable_averaging = false, .min_acquisition_ns = 220, .enabled = true };
&channel_config);

// Release ADC and channel objects when no longer needed


The following snippet initializes an ADC with one single-ended channel and one differential channel

    cy_rslt_t           rslt;

// Use the same configuration for both channels
{ .enable_averaging = false, .min_acquisition_ns = 220, .enabled = true };

// Initialize a channel to scan P10_0 with the default vminus
&channel_config);

// Initialize a differential channel for the pair of P10_2 and P10_3
&channel_config);

// Read the ADC conversion results for both channels. Repeat as necessary.

// Release ADC and channel objects when no longer needed


Snippet 3: Asynchronously read multiple channels

The following snippet illustrates how to asynchronously read multiple scans of multiple channels.


#define NUM_CHANNELS (2)
#define NUM_SCAN     (3)
{
// Note: arg is configured below to be a pointer to the destination array
{
int32_t* result_arr = (int32_t*)arg;
for (int scan = 0; scan < NUM_SCAN; ++scan)
{
for (int channel = 0; channel < NUM_CHANNELS; ++channel)
{
// Perform application-specific processing of the ADC result
process_adc_result(channel, result_arr[(scan * NUM_CHANNELS) + channel]);
}
}
}
}

{
// Initialize the ADC and its channels as shown in Snippet 2

int32_t result_arr[NUM_CHANNELS * NUM_SCAN];
// Register a callback and set the callback argument to be a pointer to the result array so that
// we can easily reference it in the event handler.

// Subscribe to the async read complete event so that we we can process the results when they
// are available
true);

// Initiate an asynchronous read operation. The event handler will be called when it is
// complete.
}



Snippet 4: Continuous scanning

This snippet shows how to run the ADC in continuous mode and process results as each scan completes.



{
CY_UNUSED_PARAMETER(arg);
CY_UNUSED_PARAMETER(event);
// Note: arg is configured below to be a pointer to the adc object
if (0u != (event & CYHAL_ADC_EOS))
{
for (int i = 0; i < NUM_CHANNELS; ++i)
{
// Perform application-specific processing of the ADC result
}
}
}

{
// Initialize the each member of the adc_channels array as shown in Snippet 2
{ /* Other configuration options are omitted here for clarity */ .continuous_scanning = true };

// Register a callback and set the callback argument to be a pointer to the adc object so that
// we can easily reference it in the event handler.

// Subscribe to the end of scan event so that we we can process the results as each scan
// completes

// Call the ADC configure function to begin continuous scanning
}



Defines

CYHAL_ADC_BITS

Number of bits populated with meaningful data by each ADC sample.

CYHAL_ADC_MAX_VALUE

Maximum value that the ADC can return.

CYHAL_ADC_AVG_MODE_AVERAGE

Perform standard averaging.

Divide the accumulated value by the number of samples.

note

This is not supported in combination with CYHAL_ADC_AVG_MODE_ACCUMULATE

CYHAL_ADC_AVG_MODE_ACCUMULATE

Accumulate samples as in CYHAL_ADC_AVG_MODE_AVERAGE, but do not divide by the number of samples.

CYHAL_ADC_AVG_MODE_MAX_SHIFT

Average mode flag position indices shifted by greater than this are implementation specific.

The value of this macro is subject to change between HAL versions.

CYHAL_ADC_VNEG

Selects the default connection for the inverting input to achieve a single-ended channel.

This connection is controlled by the vneg member of cyhal_adc_config_t.

Typedefs

typedef void (*cyhal_adc_event_callback_t)(void *callback_arg, cyhal_adc_event_t event)

Enums

enum cyhal_adc_vref_t

Values:

enumerator CYHAL_ADC_REF_INTERNAL

Internal reference. See the BSP documentation for the value of this reference. (Default)

enumerator CYHAL_ADC_REF_EXTERNAL

Reference from external pin.

enumerator CYHAL_ADC_REF_VDDA

Reference from VDDA (analog supply)

enumerator CYHAL_ADC_REF_VDDA_DIV_2

Reference from VDDA (analog supply) divided by 2.

enum cyhal_adc_vneg_t

cyhal_adc_vneg_t: Vminus selection for single-ended channels.

Values:

enumerator CYHAL_ADC_VNEG_VSSA

Connect vminus to ground.

enumerator CYHAL_ADC_VNEG_VREF

Connect vminus to the selected vref (see cyhal_adc_vref_t)

enum cyhal_adc_event_t

Values:

enumerator CYHAL_ADC_EOS

End of scan: a scan of all channels has completed. Only applicable when continuously scanning.

enumerator CYHAL_ADC_ASYNC_READ_COMPLETE

An asynchronous read operation has completed.

enum cyhal_adc_input_t

Values:

enumerator CYHAL_ADC_INPUT_START_SCAN
enum cyhal_adc_output_t

Values:

enumerator CYHAL_ADC_OUTPUT_SCAN_COMPLETE

Functions

cy_rslt_t cyhal_adc_init(cyhal_adc_t *obj, cyhal_gpio_t pin, const cyhal_clock_t *clk)

The ADC will be initialized with the following default configuration:

• Sample rate: See implementation-specific documentation

• Average count: 1 (averaging disabled).

• Continuous scanning: false

• External vref: NC

• Bypassed: false

• Bypass pin: NC

• Power level: CYHAL_POWER_LEVEL_DEFAULT

To change the configuration, see cyhal_adc_configure

Return

The status of the init request. CY_RSLT_SUCCESS is returned on success. On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [out] obj: Pointer to an ADC object. The caller must allocate the memory for this object but the init function will initialize its contents.

• [in] pin: A pin corresponding to the ADC block to initialize Note: This pin is not reserved, it is just used to identify which ADC block to allocate. If multiple channels will be allocated for a single ADC instance, only one pin should be passed here; it does not matter which one. After calling this function once, call cyhal_adc_channel_init_diff once for each pin whose value should be measured.

• [in] clk: The clock to use can be shared, if not provided a new clock will be allocated

void cyhal_adc_free(cyhal_adc_t *obj)

Parameters
• [inout] obj: The ADC object

cy_rslt_t cyhal_adc_configure(cyhal_adc_t *obj, const cyhal_adc_config_t *config)

note

If a scan is in progress, this may cause it to be interrupted.

Return

The status of the configuration request On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: The ADC object

• [in] config: The configuration to apply

cy_rslt_t cyhal_adc_set_power(cyhal_adc_t *obj, cyhal_power_level_t power)

Changes the current operating power level of the ADC.

If the power level is set to CYHAL_POWER_LEVEL_OFF, the ADC will be powered-off but it will retain its configuration, so it is not necessary to reconfigure it when changing the power level from CYHAL_POWER_LEVEL_OFF to any other value.

Return

The status of the set power request On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: ADC object

• [in] power: The power level to set

cy_rslt_t cyhal_adc_set_sample_rate(cyhal_adc_t *obj, uint32_t desired_sample_rate_hz, uint32_t *achieved_sample_rate_hz)

Configure the number of samples per second.

This is the number of times each enabled channel is sampled per second. The total number of samples performed by the ADC hardware per second is equal to sample_rate_hz / num_channels_enabled. Depending on the system clock configuration or limitations of the underlying hardware, it may not be possible to achieve precisely the desired sample rate. The achived_sample_rate_hz parameter will be updated to indicate the sample rate that was achived.

note

The achieved_sample_rate_hz value is only valid while the configuration of the ADC and its channels remains umodified. If cyhal_adc_configure, cyhal_adc_channel_init_diff, cyhal_adc_channel_configure, or cyhal_adc_channel_free is called, it is necessary to call this function again in order to update the sample rate. Therefore, it is recommended to call this function after the ADC and all channels have been configured.

Return

The status of the sample rate request. Note that inability to exactly match the requested sample rate is not considered an error. It is the application’s responsibility to determine whether the achived rate is within the tolerance that it requires. CY_RSLT_SUCCESS is returned on success.

On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: The ADC object to configure

• [in] desired_sample_rate_hz: The desired sample rate, in hertz

• [out] achieved_sample_rate_hz: The achieved sample rate, in hertz

cy_rslt_t cyhal_adc_channel_init_diff(cyhal_adc_channel_t *obj, cyhal_adc_t *adc, cyhal_gpio_t vplus, cyhal_gpio_t vminus, const cyhal_adc_channel_config_t *cfg)

note

: Some platforms may restrict which pins can be used as part of a differential pair. See the implementation-specific documentation for details.

Configures the pin used by ADC.

Return

The status of the init request. On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [out] obj: The ADC channel object to initialize

• [in] adc: The ADC for which the channel should be initialized

• [in] vplus: Non-inverting input

• [in] vminus: Inverting input. For a single ended channel, use CYHAL_ADC_VNEG.

• [in] cfg: The ADC channel configuration

cy_rslt_t cyhal_adc_channel_configure(cyhal_adc_channel_t *obj, const cyhal_adc_channel_config_t *config)

note

If a scan is in progress, this may cause it to be interrupted. It is not valid to change the enabled state of a channel while an asynchronous read operation is in progress.

Return

The status of the configuration request On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: The ADC channel object

• [in] config: The configuration to apply

void cyhal_adc_channel_free(cyhal_adc_channel_t *obj)

Parameters
• [inout] obj: The ADC channel object

uint16_t cyhal_adc_read_u16(const cyhal_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).

Return

An unsigned 16bit value representing the current input voltage

Parameters
• [in] obj: The ADC object

int32_t cyhal_adc_read(const cyhal_adc_channel_t *obj)

Read the value from ADC pin, represented as a 32-bit signed, right-aligned value.

This is a ‘resolution’-bit value, sign-extended to 32 bits. If the vplus signal is below the vminus signal, the result will be negative. If the vplus signal is above the vminus signal, the result will be positive. 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).

Return

A signed 32 bit value representing the current input voltage

Parameters
• [in] obj: The ADC object

int32_t cyhal_adc_read_uv(const cyhal_adc_channel_t *obj)

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

Return

An unsigned 32 bit value representing the current input in microvolts

Parameters
• [in] obj: The ADC object

cy_rslt_t cyhal_adc_read_async(cyhal_adc_t *obj, size_t num_scan, int32_t *result_list)

Scan the specified ADC channels in the background and copy the results into the array pointed to by result_list.

Results are represented as 32-bit signed, right-aligned values. That is, they are ‘resolution’-bit values, sign-extended to 32 bits. If the vplus signal is below the vminus signal, the result will be negative. If the vplus signal is above the vminus signal, the result will be positive.

If continuous scanning is disabled, this will trigger num_scan new scans and copy the results into result_list once the scan is completed.

If continuous scanning is enabled, this will copy the results of num_scan scans into the result_list as they complete, beginning with the most recently completed scan (if one exists).

Scan results are placed sequentially into result_list. That is, result_list will contain all of the results from the first scan, followed by all of the results from the second scan, etc. If channels exist that are initialized but not enabled, they will consume locations in result_list, but these values are undefined.

When the requested number of scans have been completed, the CYHAL_ADC_ASYNC_READ_COMPLETE event will be raised.

cyhal_adc_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer.

Return

The status of the read async request On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: ADC to read from

• [in] num_scan: The number of scans of each channel that should be read

• [in] result_list: The array where results should be. This must be of length num_scan * initialized_channels, where initialized_channels is the number of channels that have been initialized for this ADC (and not later freed) via cyhal_adc_channel_init_diff

cy_rslt_t cyhal_adc_read_async_uv(cyhal_adc_t *obj, size_t num_scan, int32_t *result_list)

Scan the specified ADC channels in the background and copy the conversion results in microvolts into the array pointed to by result_list.

If continuous scanning is disabled, this will trigger num_scan new scans and copy the results into result_list once the scan is completed.

If continuous scanning is enabled, this will copy the results of num_scan scans into the result_list as they complete, beginning with the most recently completed scan (if one exists).

Scan results are placed sequentially into result_list. That is, result_list will contain all of the results from the first scan, followed by all of the results from the second scan, etc. If channels exist that are initialized but not enabled, they will consume locations in result_list, but these values are undefined.

When the requested number of scans have been completed, the CYHAL_ADC_ASYNC_READ_COMPLETE event will be raised.

cyhal_adc_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer.

Return

The status of the read async request On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: ADC to read from

• [in] num_scan: The number of scans of each channel that should be read

• [in] result_list: The array where results should be. This must be of length num_scan * initialized_channels, where initialized_channels is the number of channels that have been initialized for this ADC (and not later freed) via cyhal_adc_channel_init_diff

cy_rslt_t cyhal_adc_set_async_mode(cyhal_adc_t *obj, cyhal_async_mode_t mode, uint8_t dma_priority)

Set the mechanism that is used to perform ADC asynchronous transfers.

The default is SW.

warning

The effect of calling this function while an async transfer is pending is undefined.

Return

The status of the set mode request On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.

For all other return codes, please refer to device driver documentation available in the BSP landing page

Parameters
• [in] obj: The ADC object

• [in] mode: The transfer mode

• [in] dma_priority: The priority, if DMA is used. Valid values are the same as for cyhal_dma_init. If DMA is not selected, the only valid value is CYHAL_DMA_PRIORITY_DEFAULT, and no guarantees are made about prioritization.

void cyhal_adc_register_callback(cyhal_adc_t *obj, cyhal_adc_event_callback_t callback, void *callback_arg)

This function will be called when one of the events enabled by cyhal_adc_enable_event occurs.

Parameters
• [in] obj: The ADC object

• [in] callback: The callback handler which will be invoked when the interrupt fires

• [in] callback_arg: Generic argument that will be provided to the callback when called

void cyhal_adc_enable_event(cyhal_adc_t *obj, cyhal_adc_event_t event, uint8_t intr_priority, bool enable)

When an enabled event occurs, the function specified by cyhal_adc_register_callback will be called.

Parameters
• [in] obj: The ADC object

• [in] event: The ADC event type

• [in] intr_priority: The priority for NVIC interrupt events

• [in] enable: True to turn on specified events, False to turn off

cy_rslt_t cyhal_adc_connect_digital(cyhal_adc_t *obj, cyhal_source_t source, cyhal_adc_input_t input)

Connects a source signal and enables the specified input.

Return

The status of the connection

Parameters
• [in] obj: The ADC object

• [in] source: Source signal obtained from another driver’s cyhal_<PERIPH>_enable_output

• [in] input: Which input signal to connect to

cy_rslt_t cyhal_adc_enable_output(cyhal_adc_t *obj, cyhal_adc_output_t output, cyhal_source_t *source)

Enables the specified output signal.

Return

The status of the output enable

Parameters
• [in] obj: The ADC object

• [in] output: Which output signal to enable

• [out] source: Pointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.

cy_rslt_t cyhal_adc_disconnect_digital(cyhal_adc_t *obj, cyhal_source_t source, cyhal_adc_input_t input)

Disconnect a source signal and disable ADC input.

Return

The status of the disconnect

Parameters
• [in] obj: The ADC object

• [in] source: Source signal from cyhal_<PERIPH>_enable_output to disable

• [in] input: Which input signal to disconnect

cy_rslt_t cyhal_adc_disable_output(cyhal_adc_t *obj, cyhal_adc_output_t output)

Disables specified output signal from ADC.

Return

The status of the disablement

Parameters
• [in] obj: The ADC object

• [in] output: Which output signal to disable

struct cyhal_adc_config_t

Public Members

bool continuous_scanning

Whether the ADC samples continuously (true) or only on demand (false).

When configured to true, the ADC will immediately begin scanning all configured channels. When configured to false, the ADC will stop continuous scanning at the completion of the current scan

uint8_t resolution

See the implementation specific documentation for supported values

uint16_t average_count

The number of samples that should be averaged together to obtain a result.

A value of 1 disables averaging.

uint32_t average_mode_flags

Flags to control the behavior of the averaging functionality when average_count is greater than 1.

This field contains zero or more flags that are OR’d together. All implementations define CYHAL_ADC_AVG_MODE_AVERAGE and CYHAL_ADC_AVG_MODE_ACCUMULATE (though some may not support both modes). Some implementations may define other flags to control additional aspects of the averaging functionality; see the implementation-specific documentation for details.

uint32_t ext_vref_mv

The external voltage reference value, in millivolts.

If vref is set to CYHAL_ADC_REF_EXTERNAL, this must be nonzero. If vref is set to anything other than CYHAL_ADC_REF_EXTERNAL, this must be zero.

cyhal_adc_vneg_t vneg

Vminus selection for single-ended channels.

cyhal_adc_vref_t vref

cyhal_gpio_t ext_vref

The GPIO that should be used for the external reference.

If CYHAL_ADC_REF_EXTERNAL is selected and the current target uses a GPIO for ADC ext_vref (see the BSP documentation), this must not be NC. If the current target uses a dedicated pin (not a GPIO) for ADC ext_vref, or if any other reference is selected, this must be NC.

bool is_bypassed

Whether an external bypass capacitor should be used.

Depending on the platform this may be required to reduce noise at sufficiently high sample rates. See the implementation specific documentation for details.

cyhal_gpio_t bypass_pin

The GPIO pin that should be used for the bypass capacitor.

If is_bypassed is true and the current target uses a GPIO for the bypass capacitor connection, this must not be NC. Otherwise, this must be NC. Depending on the device, this may be the same GPIO as ext_vref. See the BSP documentation for details.

struct cyhal_adc_channel_config_t

Public Members

bool enabled

Whether this channel should be sampled when the ADC performs a scan.

bool enable_averaging

Enable or disable averaging for this channel.

All other aspects of the averging functionality are configured in cyhal_adc_config_t

uint32_t min_acquisition_ns

Minimum time that this channel should be sampled, in nanoseconds.

The actual time may be greater than this depending on hardware limitations, the sample rate, and the configuration of other channels.

note

While this value is specified in ns, the underlying hardware generally does not support acquisition time with a granularity of 1 ns. See the implementation specific documentation for details.