Hardware Abstraction Layer (HAL)
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);
bool enable_averaging
Enable or disable averaging for this channel.
Definition: cyhal_adc.h:227
#define CYHAL_ADC_VNEG
Selects the default connection for the inverting input to achieve a single-ended channel.
Definition: cyhal_adc.h:170
void cyhal_adc_channel_free(cyhal_adc_channel_t *obj)
Uninitialize the ADC channel and cyhal_adc_channel_t 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.
cy_rslt_t cyhal_adc_init(cyhal_adc_t *obj, cyhal_gpio_t pin, const cyhal_clock_t *clk)
Initialize ADC peripheral.
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.
void cyhal_adc_free(cyhal_adc_t *obj)
Uninitialize the ADC peripheral and cyhal_adc_t object.
ADC Channel Configuration.
Definition: cyhal_adc.h:221
ADC channel object.
Definition: cyhal_hw_types.h:547
ADC object.
Definition: cyhal_hw_types.h:456
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

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
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);
}
void cyhal_adc_enable_event(cyhal_adc_t *obj, cyhal_adc_event_t event, uint8_t intr_priority, bool enable)
Configure ADC events.
cyhal_adc_event_t
ADC events.
Definition: cyhal_adc.h:139
void cyhal_adc_register_callback(cyhal_adc_t *obj, cyhal_adc_event_callback_t callback, void *callback_arg)
Register an ADC callback handler.
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 r...
@ CYHAL_ADC_ASYNC_READ_COMPLETE
An asynchronous read operation has completed.
Definition: cyhal_adc.h:141
#define CYHAL_ISR_PRIORITY_DEFAULT
Priority that is applied by default to all drivers when initialized.
Definition: cyhal_hw_types.h:114

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
{ /* 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
// Call the ADC configure function to begin continuous scanning
cyhal_adc_configure(&adc_obj, &config);
}
bool continuous_scanning
Whether the ADC samples continuously (true) or only on demand (false).
Definition: cyhal_adc.h:180
cy_rslt_t cyhal_adc_configure(cyhal_adc_t *obj, const cyhal_adc_config_t *config)
Update the ADC configuration.
@ CYHAL_ADC_EOS
End of scan: a scan of all channels has completed. Only applicable when continuously scanning.
Definition: cyhal_adc.h:140
ADC Configuration.
Definition: cyhal_adc.h:174

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

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

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

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:

To change the configuration, see cyhal_adc_configure

Parameters
[out]objPointer to an ADC object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]pinA 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]clkThe 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]adcPointer to an adc object. The caller must allocate the memory for this object but the init function will initialize its contents.
[out]channelsArray 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_channelsLength 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]cfgConfiguration 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]objThe 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]objThe ADC object
[in]configThe 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]objADC object
[in]powerThe 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]objThe ADC object to configure
[in]desired_sample_rate_hzThe desired sample rate, in hertz
[out]achieved_sample_rate_hzThe 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]objThe ADC channel object to initialize
[in]adcThe ADC for which the channel should be initialized
[in]vplusNon-inverting input
[in]vminusInverting input. For a single ended channel, use CYHAL_ADC_VNEG.
[in]cfgThe 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]objThe ADC channel object
[in]configThe 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]objThe 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]objThe 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]objThe 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]objThe 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]objADC to read from
[in]num_scanThe number of scans of each channel that should be read
[in]result_listThe 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]objADC to read from
[in]num_scanThe number of scans of each channel that should be read
[in]result_listThe 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]objThe ADC object
[in]modeThe transfer mode
[in]dma_priorityThe 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]objThe ADC object
[in]callbackThe callback handler which will be invoked when the interrupt fires
[in]callback_argGeneric 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]objThe ADC object
[in]eventThe ADC event type
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue 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]objThe ADC object
[in]sourceSource signal obtained from another driver's cyhal_<PERIPH>_enable_output
[in]inputWhich 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]objThe ADC object
[in]outputWhich output signal to enable
[out]sourcePointer 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]objThe ADC object
[in]sourceSource signal from cyhal_<PERIPH>_enable_output to disable
[in]inputWhich 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]objThe ADC object
[in]outputWhich output signal to disable
Returns
The status of the disablement