ADC (Analog to Digital Converter)

General Description

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 cyhal_adc_read for reading the results.
See Snippet 1: Simple ADC initialization and reading conversion result.

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

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;
    cyhal_adc_t         adc_obj;
    cyhal_adc_channel_t adc_chan_0_obj;
    // ADC conversion result.
    int32_t adc_out;
 
    // Initialize ADC. The ADC block which can connect to pin ADC_VPLUS1 is selected
    rslt = cyhal_adc_init(&adc_obj, ADC_VPLUS1, NULL);
 
    // Initialize ADC channel, allocate channel number 0 to pin ADC_VPLUS1 as this is the first
    // channel initialized
    const cyhal_adc_channel_config_t channel_config =
        { .enable_averaging = false, .min_acquisition_ns = 220, .enabled = true };
    rslt = cyhal_adc_channel_init_diff(&adc_chan_0_obj, &adc_obj, ADC_VPLUS1, CYHAL_ADC_VNEG,
                                       &channel_config);
 
    // Read the ADC conversion result for corresponding ADC channel. Repeat as necessary.
    adc_out = cyhal_adc_read(&adc_chan_0_obj);
 
    // Release ADC and channel objects when no longer needed
    cyhal_adc_channel_free(&adc_chan_0_obj);
    cyhal_adc_free(&adc_obj);

Snippet 2: Multi-channel ADC initialization and reading conversion result

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

    cy_rslt_t           rslt;
    cyhal_adc_t         adc_obj;
    cyhal_adc_channel_t adc_chan_0_obj;
    cyhal_adc_channel_t adc_chan_1_obj;
    // 32-bit ADC conversion result
    int32_t adc_out_0;
    int32_t adc_out_1;
 
    // Use the same configuration for both channels
    const cyhal_adc_channel_config_t channel_config =
        { .enable_averaging = false, .min_acquisition_ns = 220, .enabled = true };
 
    /* Initialize ADC. The ADC block which can connect to pin ADC_VPLUS1 is selected */
    rslt = cyhal_adc_init(&adc_obj, ADC_VPLUS1, NULL);
 
    // Initialize a channel to scan P10_0 with the default vminus
    rslt = cyhal_adc_channel_init_diff(&adc_chan_0_obj, &adc_obj, ADC_VPLUS1, CYHAL_ADC_VNEG,
                                       &channel_config);
 
    // Initialize a differential channel for the pair of P10_2 and P10_3
    rslt = cyhal_adc_channel_init_diff(&adc_chan_1_obj, &adc_obj, ADC_VPLUS2, ADC_VMINUS2,
                                       &channel_config);
 
    // Read the ADC conversion results for both channels. Repeat as necessary.
    adc_out_0 = cyhal_adc_read(&adc_chan_0_obj);
    adc_out_1 = cyhal_adc_read(&adc_chan_1_obj);
 
    // Release ADC and channel objects when no longer needed
    cyhal_adc_channel_free(&adc_chan_0_obj);
    cyhal_adc_channel_free(&adc_chan_1_obj);
    cyhal_adc_free(&adc_obj);
 

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)
static void adc_event_handler(void* arg, cyhal_adc_event_t event)
{
    // Note: arg is configured below to be a pointer to the destination array
    if (0u != (event & CYHAL_ADC_ASYNC_READ_COMPLETE))
    {
        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]);
            }
        }
    }
}
 
 
void snippet_cyhal_adc_read_async(void)
{
    cyhal_adc_t adc_obj;
    // 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.
    cyhal_adc_register_callback(&adc_obj, &adc_event_handler, result_arr);
 
    // Subscribe to the async read complete event so that we we can process the results when they
    // are available
    cyhal_adc_enable_event(&adc_obj, CYHAL_ADC_ASYNC_READ_COMPLETE, CYHAL_ISR_PRIORITY_DEFAULT,
                           true);
 
    // Initiate an asynchronous read operation. The event handler will be called when it is
    // complete.
    cyhal_adc_read_async(&adc_obj, NUM_SCAN, result_arr);
}
 
 

Snippet 4: Continuous scanning

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

 
static cyhal_adc_channel_t adc_channels[NUM_CHANNELS];
 
static void adc_continuous_event_handler(void* arg, cyhal_adc_event_t event)
{
    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
            process_adc_result(i, cyhal_adc_read(&adc_channels[i]));
        }
    }
}
 
 
void snippet_cyhal_adc_continuous_read(void)
{
    cyhal_adc_t adc_obj;
    // Initialize the each member of the adc_channels array as shown in Snippet 2
    cyhal_adc_config_t config =
    { /* 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.
    cyhal_adc_register_callback(&adc_obj, &adc_continuous_event_handler, &adc_obj);
 
    // Subscribe to the end of scan event so that we we can process the results as each scan
    // completes
    cyhal_adc_enable_event(&adc_obj, CYHAL_ADC_EOS, CYHAL_ISR_PRIORITY_DEFAULT, true);
 
    // Call the ADC configure function to begin continuous scanning
    cyhal_adc_configure(&adc_obj, &config);
}
 
 

API Reference
	ADC HAL Results
	ADC specific return codes.

Data Structures
struct	cyhal_adc_config_t
	ADC Configuration. More...
struct	cyhal_adc_channel_config_t
	ADC Channel Configuration. More...

Macros
#define	CYHAL_ADC_BITS   16
	Number of bits populated with meaningful data by each ADC sample.
#define	CYHAL_ADC_MAX_VALUE   ((1 << CYHAL_ADC_BITS) - 1)
	Maximum value that the ADC can return.
#define	CYHAL_ADC_AVG_MODE_AVERAGE   (1u << 0)
	Perform standard averaging. More...
#define	CYHAL_ADC_AVG_MODE_ACCUMULATE   (1u << 1)
	Accumulate samples as in CYHAL_ADC_AVG_MODE_AVERAGE, but do not divide by the number of samples.
#define	CYHAL_ADC_AVG_MODE_MAX_SHIFT   (1u)
	Average mode flag position indices shifted by greater than this are implementation specific. More...
#define	CYHAL_ADC_VNEG   CYHAL_NC_PIN_VALUE
	Selects the default connection for the inverting input to achieve a single-ended channel. More...

Typedefs
typedef void(*	cyhal_adc_event_callback_t) (void *callback_arg, cyhal_adc_event_t event)
	Handler for ADC event callbacks.

Enumerations
enum	cyhal_adc_vref_t {   CYHAL_ADC_REF_INTERNAL ,   CYHAL_ADC_REF_EXTERNAL ,   CYHAL_ADC_REF_VDDA ,   CYHAL_ADC_REF_VDDA_DIV_2 }
	Possible selections for ADC reference. More...
enum	cyhal_adc_vneg_t {   CYHAL_ADC_VNEG_VSSA ,   CYHAL_ADC_VNEG_VREF }
	Vminus selection for single-ended channels. More...
enum	cyhal_adc_event_t {   CYHAL_ADC_EOS = 1u ,   CYHAL_ADC_ASYNC_READ_COMPLETE = 2u }
	ADC events. More...
enum	cyhal_adc_input_t { CYHAL_ADC_INPUT_START_SCAN }
	Selections for ADC input signals
enum	cyhal_adc_output_t { CYHAL_ADC_OUTPUT_SCAN_COMPLETE }
	Selections for ADC output signals

Functions
cy_rslt_t	cyhal_adc_init (cyhal_adc_t *obj, cyhal_gpio_t pin, const cyhal_clock_t *clk)
	Initialize ADC peripheral. More...
cy_rslt_t	cyhal_adc_init_cfg (cyhal_adc_t *adc, cyhal_adc_channel_t **channels, uint8_t *num_channels, const cyhal_adc_configurator_t *cfg)
	Initialize the ADC peripheral and its channels using a configurator generated configuration struct. More...
void	cyhal_adc_free (cyhal_adc_t *obj)
	Uninitialize the ADC peripheral and cyhal_adc_t object. More...
cy_rslt_t	cyhal_adc_configure (cyhal_adc_t *obj, const cyhal_adc_config_t *config)
	Update the ADC configuration. More...
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. More...
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. More...
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)
	Initialize a differential ADC channel. More...
cy_rslt_t	cyhal_adc_channel_configure (cyhal_adc_channel_t *obj, const cyhal_adc_channel_config_t *config)
	Update the ADC channel configuration. More...
void	cyhal_adc_channel_free (cyhal_adc_channel_t *obj)
	Uninitialize the ADC channel and cyhal_adc_channel_t object. More...
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. More...
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. More...
int32_t	cyhal_adc_read_uv (const cyhal_adc_channel_t *obj)
	Read the value from ADC pin, in microvolts. More...
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. More...
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. More...
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. More...
void	cyhal_adc_register_callback (cyhal_adc_t *obj, cyhal_adc_event_callback_t callback, void *callback_arg)
	Register an ADC callback handler. More...
void	cyhal_adc_enable_event (cyhal_adc_t *obj, cyhal_adc_event_t event, uint8_t intr_priority, bool enable)
	Configure ADC events. More...
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. More...
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. More...
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. More...
cy_rslt_t	cyhal_adc_disable_output (cyhal_adc_t *obj, cyhal_adc_output_t output)
	Disables specified output signal from ADC. More...

---

Data Structure Documentation

cyhal_adc_config_t

struct cyhal_adc_config_t

Data Fields
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	ADC 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	ADC voltage reference.
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.

cyhal_adc_channel_config_t

struct cyhal_adc_channel_config_t

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

Macro Definition Documentation

CYHAL_ADC_AVG_MODE_AVERAGE

#define CYHAL_ADC_AVG_MODE_AVERAGE   (1u << 0)

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_MAX_SHIFT

#define CYHAL_ADC_AVG_MODE_MAX_SHIFT   (1u)

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

#define CYHAL_ADC_VNEG   CYHAL_NC_PIN_VALUE

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.

Enumeration Type Documentation

cyhal_adc_vref_t

enum cyhal_adc_vref_t

Possible selections for ADC reference.

Enumerator
CYHAL_ADC_REF_INTERNAL	Internal reference. See the BSP documentation for the value of this reference. (Default)
CYHAL_ADC_REF_EXTERNAL	Reference from external pin.
CYHAL_ADC_REF_VDDA	Reference from VDDA (analog supply)
CYHAL_ADC_REF_VDDA_DIV_2	Reference from VDDA (analog supply) divided by 2.

cyhal_adc_vneg_t

enum cyhal_adc_vneg_t

Vminus selection for single-ended channels.

Enumerator
CYHAL_ADC_VNEG_VSSA	Connect vminus to ground.
CYHAL_ADC_VNEG_VREF	Connect vminus to the selected vref (see cyhal_adc_vref_t)

cyhal_adc_event_t

enum cyhal_adc_event_t

ADC events.

Enumerator
CYHAL_ADC_EOS	End of scan: a scan of all channels has completed. Only applicable when continuously scanning.
CYHAL_ADC_ASYNC_READ_COMPLETE	An asynchronous read operation has completed.

Function Documentation

cyhal_adc_init()

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

Initialize ADC peripheral.

The ADC will be initialized with the following default configuration:

• Sample rate: See implementation-specific documentation
• Average count: 1 (averaging disabled).
• Continuous scanning: false
• Single ended vneg: CYHAL_ADC_VNEG_VREF
• Vref: CYHAL_ADC_REF_INTERNAL
• External vref: NC
• Bypassed: false
• Bypass pin: NC
• Power level: CYHAL_POWER_LEVEL_DEFAULT

To change the configuration, see cyhal_adc_configure

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

Returns

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

cyhal_adc_init_cfg()

cy_rslt_t cyhal_adc_init_cfg	(	cyhal_adc_t *	adc,
		cyhal_adc_channel_t **	channels,
		uint8_t *	num_channels,
		const cyhal_adc_configurator_t *	cfg
	)

Initialize the ADC peripheral and its channels using a configurator generated configuration struct.

Parameters

[out]	adc	Pointer to an adc object. The caller must allocate the memory for this object but the init function will initialize its contents.
[out]	channels	Array of pointers to ADC channel objects. This array must contain a minimum of one (non-null) entry per channel that is enabled by the configurator
[in,out]	num_channels	Length of the channels array. If this value is too small for all of the channels enabled by the configurator an error will be returned. Will be updated with the number of channels that were enabled by the configurator.
[in]	cfg	Configuration structure generated by the configurator.

Returns

The status of the init request

cyhal_adc_free()

void cyhal_adc_free

(

cyhal_adc_t *

obj

)

Uninitialize the ADC peripheral and cyhal_adc_t object.

Parameters

[in,out]

obj

The ADC object

cyhal_adc_configure()

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

Update the ADC configuration.

Note

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

Parameters

[in]	obj	The ADC object
[in]	config	The configuration to apply

Returns

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

cyhal_adc_set_power()

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.

Parameters

[in]	obj	ADC object
[in]	power	The power level to set

Returns

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

cyhal_adc_set_sample_rate()

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.

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

Returns

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

cyhal_adc_channel_init_diff()

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
	)

Initialize a differential ADC channel.

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.

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

Returns

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

cyhal_adc_channel_configure()

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

Update the ADC channel configuration.

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.

Parameters

[in]	obj	The ADC channel object
[in]	config	The configuration to apply

Returns

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

cyhal_adc_channel_free()

void cyhal_adc_channel_free

(

cyhal_adc_channel_t *

obj

)

Uninitialize the ADC channel and cyhal_adc_channel_t object.

Parameters

[in,out]

obj

The ADC channel object

cyhal_adc_read_u16()

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

Parameters

[in]

obj

The ADC object

Returns

An unsigned 16bit value representing the current input voltage

cyhal_adc_read()

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

Parameters

[in]

obj

The ADC object

Returns

A signed 32 bit value representing the current input voltage

cyhal_adc_read_uv()

int32_t cyhal_adc_read_uv

(

const cyhal_adc_channel_t *

obj

)

Read the value from ADC pin, in microvolts.

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 32 bit value representing the current input in microvolts

cyhal_adc_read_async()

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.

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

Returns

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

cyhal_adc_read_async_uv()

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.

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

Returns

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

cyhal_adc_set_async_mode()

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.

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.

Returns

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

cyhal_adc_register_callback()

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

Register an ADC callback handler.

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

cyhal_adc_enable_event()

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

Configure ADC events.

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

cyhal_adc_connect_digital()

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.

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

Returns

The status of the connection

cyhal_adc_enable_output()

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.

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.

Returns

The status of the output enable

cyhal_adc_disconnect_digital()

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.

Parameters

[in]	obj	The ADC object
[in]	source	Source signal from cyhal_<PERIPH>_enable_output to disable
[in]	input	Which input signal to disconnect

Returns

The status of the disconnect

cyhal_adc_disable_output()

cy_rslt_t cyhal_adc_disable_output	(	cyhal_adc_t *	obj,
		cyhal_adc_output_t	output
	)

Disables specified output signal from ADC.

Parameters

[in]	obj	The ADC object
[in]	output	Which output signal to disable

Returns

The status of the disablement