SAADC driver

group nrfx_saadc

Successive Approximation Analog-to-Digital Converter (SAADC) peripheral driver.

Defines

NRFX_SAADC_DEFAULT_ACQTIME: Auxiliary symbol specifying default value for the SAADC acquisition time.

NRFX_SAADC_DEFAULT_CONV_TIME: Auxiliary symbol specifying default value for the SAADC conversion time.

NRFX_SAADC_DEFAULT_CHANNEL_SE(_pin_p, _index)

SAADC channel default configuration for the single-ended mode.

This configuration sets up single-ended SAADC channel with the following options:

resistor ladder disabled
gain: 1
reference voltage: internal
sample acquisition time: 10 us
burst disabled

See also

nrfx_saadc_adv_config_t

Parameters:

_pin_p – [in] Positive input analog pin.
_pin_n – [in] Negative input analog pin.
_index – [in] Channel index.

Typedefs

typedef void (*nrfx_saadc_event_handler_t)(nrfx_saadc_evt_t const *p_event)

SAADC driver event handler.

When operating in the advanced mode:

when the sampling is performed by the external timer, the external timer can be safely started on NRFX_SAADC_EVT_READY and stopped on NRFX_SAADC_EVT_FINISHED.
call the nrfx_saadc_buffer_set() on NRFX_SAADC_EVT_BUF_REQ to achieve the continuous conversion.

Param p_event:: [in] Pointer to an SAADC driver event. The event structure is allocated on the stack, so it is valid only within the context of the event handler.

Enums

enum nrfx_saadc_evt_type_t

SAADC driver event types.

Values:

enumerator NRFX_SAADC_EVT_DONE: Event generated when the buffer is filled with samples.

enumerator NRFX_SAADC_EVT_LIMIT: Event generated when one of the limits is reached.

enumerator NRFX_SAADC_EVT_CALIBRATEDONE: Event generated when the calibration is complete.

enumerator NRFX_SAADC_EVT_BUF_REQ: Event generated when the next buffer for continuous conversion is requested.

enumerator NRFX_SAADC_EVT_READY: Event generated when the first buffer is acquired by the peripheral and sampling can be started.

enumerator NRFX_SAADC_EVT_FINISHED: Event generated when all supplied buffers are filled with results.

Functions

nrfx_err_t nrfx_saadc_init(uint8_t interrupt_priority)

Function for initializing the SAADC driver.

Parameters:

interrupt_priority – [in] Interrupt priority.

Return values:

NRFX_SUCCESS – Initialization was successful.
NRFX_ERROR_ALREADY – The driver is already initialized.
NRFX_ERROR_INVALID_STATE – The driver is already initialized. Deprecated - use NRFX_ERROR_ALREADY instead.

void nrfx_saadc_uninit(void)

Function for uninitializing the SAADC driver.

This function stops all ongoing conversions and disables all channels.

bool nrfx_saadc_init_check(void)

Function for checking if the SAADC driver is initialized.

Return values:

true – Driver is already initialized.
false – Driver is not initialized.

nrfx_err_t nrfx_saadc_channels_config(nrfx_saadc_channel_t const *p_channels, uint32_t channel_count)

Function for configuring multiple SAADC channels.

Note

The values of the nrf_saadc_channel_config_t::burst fields in channel configurations are ignored. They will be overridden with the value suitable for the selected driver operation mode.

Note

The desired mode (simple or advanced) must be set after the channels are configured.

Warning

This function overrides previous configuration done on any channel by nrfx_saadc_channels_config or nrfx_saadc_channel_config.

Parameters:

p_channels – [in] Pointer to the array of channel configuration structures.
channel_count – [in] Number of channels to be configured.

Return values:

NRFX_SUCCESS – Configuration was successful.
NRFX_ERROR_BUSY – There is a conversion or calibration ongoing.
NRFX_ERROR_INVALID_PARAM – Attempt to configure the same channel more than once.

nrfx_err_t nrfx_saadc_channel_config(nrfx_saadc_channel_t const *p_channel)

Function for configuring single SAADC channel.

Note

The values of the nrf_saadc_channel_config_t::burst fields in channel configurations are ignored. They will be overridden with the value suitable for the selected driver operation mode.

Warning

This function overrides previous configuration done on specified channel by nrfx_saadc_channels_config or nrfx_saadc_channel_config.

Parameters:

p_channel – [in] Pointer to the channel configuration structure.

Return values:

NRFX_SUCCESS – Configuration was successful.
NRFX_ERROR_BUSY – There is a conversion or calibration ongoing.

uint32_t nrfx_saadc_channels_configured_get(void)

Function for getting the currently configured SAADC channels.

Returns:: Bitmask of configured channels.

nrfx_err_t nrfx_saadc_channels_deconfig(uint32_t channel_mask)

Function for deconfiguring the specified SAADC channels.

Warning

Pins associated with the deconfigured channels will be released after next nrfx_saadc_simple_mode_set() or nrfx_saadc_advanced_mode_set() call.

Parameters:

channel_mask – [in] Bitmask of channels to be deconfigured.

Return values:

NRFX_SUCCESS – Deconfiguration was successful.
NRFX_ERROR_BUSY – There is a conversion or calibration ongoing.

nrfx_err_t nrfx_saadc_simple_mode_set(uint32_t channel_mask, nrf_saadc_resolution_t resolution, nrf_saadc_oversample_t oversampling, nrfx_saadc_event_handler_t event_handler)

Function for setting the SAADC driver in the simple mode.

The simple mode allows obtaining a single sample from each requested channel. The conversion can be done in a blocking or non-blocking manner. Sampling is initiated by calling nrfx_saadc_mode_trigger() once.

Parameters:

channel_mask – [in] Bitmask of channels to be used in the simple mode.
resolution – [in] Resolution configuration.
oversampling – [in] Oversampling configuration.
event_handler – [in] Event handler provided by the user. In case of providing NULL, the conversion will be performed in the blocking manner.

Return values:

NRFX_SUCCESS – Initialization was successful.
NRFX_ERROR_BUSY – There is a conversion or calibration ongoing.
NRFX_ERROR_INVALID_PARAM – Attempt to activate channel that is not configured.

nrfx_err_t nrfx_saadc_advanced_mode_set(uint32_t channel_mask, nrf_saadc_resolution_t resolution, nrfx_saadc_adv_config_t const *p_config, nrfx_saadc_event_handler_t event_handler)

Function for setting the SAADC driver in the advanced mode.

The advanced mode allows performing double-buffered conversions of arbitrary length. The conversions can be done in a blocking or non-blocking manner. When performing conversions in the non-blocking manner and nrfx_saadc_adv_config_t::internal_timer_cc is set to 0, sampling needs to be done by triggering NRF_SAADC_TASK_SAMPLE externally (for example by using the TIMER and/or the PPI/DPPI). When performing conversions in the non-blocking manner and nrfx_saadc_adv_config_t::start_on_end is false, the NRF_SAADC_TASK_START needs to be triggered on NRF_SAADC_EVENT_END externally (for example by using the PPI/DPPI). Sampling is initiated by calling nrfx_saadc_mode_trigger(). In case of performing conversions in the blocking manner, nrfx_saadc_mode_trigger() may need to be called several times as each call sample each requested channel once.

Note

The internal timer can only be used when a single input channel is enabled.

Note

The internal timer can only be used in the non-blocking mode.

Parameters:

channel_mask – [in] Bitmask of channels to be used in the advanced mode.
resolution – [in] Resolution configuration.
p_config – [in] Pointer to the structure with the advanced mode configuration.
event_handler – [in] Event handler provided by the user. In case of providing NULL, the conversion will be performed in the blocking manner.

Return values:

NRFX_SUCCESS – Initialization was successful.
NRFX_ERROR_BUSY – There is a conversion or calibration ongoing.
NRFX_ERROR_INVALID_PARAM – Attempt to activate channel that is not configured.
NRFX_ERROR_NOT_SUPPORTED – Attempt to activate either of the following:
- internal timer in the blocking mode,
- internal timer with multiple channels enabled,
- oversampling without burst with multiple channels enabled.

nrfx_err_t nrfx_saadc_buffer_set(nrf_saadc_value_t *p_buffer, uint16_t size)

Function for supplying the buffer to be used in the next part of the conversion.

Parameters:

p_buffer – [in] Pointer to the buffer to be filled with conversion results.
size – [in] Number of samples in the buffer.

Return values:

NRFX_SUCCESS – Buffer was supplied successfully.
NRFX_ERROR_INVALID_ADDR – The provided buffer is not in the Data RAM region.
NRFX_ERROR_INVALID_LENGTH – The provided buffer is not aligned to the number of activated channels or is too long for the EasyDMA to handle.
NRFX_ERROR_INVALID_STATE – The driver is in the idle mode.
NRFX_ERROR_ALREADY – Both buffers for double-buffered conversions are already set.

nrfx_err_t nrfx_saadc_mode_trigger(void)

Function for triggering the conversion in the configured mode.

Return values:

NRFX_SUCCESS – Operation finished successfully in the blocking manner or started successfully in the non-blocking manner.
NRFX_ERROR_BUSY – The driver is performing the conversion in the advanced blocking mode. Call the function again to continue the conversion.
NRFX_ERROR_NO_MEM – There is no buffer provided. Supply the buffer using nrfx_saadc_buffer_set() and try again.
NRFX_ERROR_INVALID_STATE – There is an ongoing conversion or calibration being performed in the non-blocking manner or the driver is in the idle mode.

void nrfx_saadc_abort(void): Function for aborting the ongoing and buffered conversions.

Note

NRFX_SAADC_EVT_DONE event will be generated if there is a conversion in progress. Event will contain number of words in the sample buffer.

Warning

Aborting blocking conversion or calibration from different context is not supported. Perform the operation in non-blocking manner instead.

nrfx_err_t nrfx_saadc_limits_set(uint8_t channel, int16_t limit_low, int16_t limit_high)

Function for setting the SAADC channel limits.

When limits are enabled and the conversion result exceeds the defined bounds, the handler function is called with the corresponding event as parameter.

Note

Before the limits are set, the driver operation mode (simple or advanced) has to be configured. Only non-blocking conversions can be monitored.

Note

Changing of the driver operation mode disables all configured limits.

Parameters:

channel – [in] Channel index.
limit_low – [in] Limit low value to generate interrupt. Use INT16_MIN to disable interrupt generation.
limit_high – [in] Limit high value to generate interrupt. Use INT16_MAX to disable interrupt generation.

Return values:

NRFX_SUCCESS – Requested channel limits were set.
NRFX_ERROR_INVALID_PARAM – Attempt to activate the limits on disabled channel.
NRFX_ERROR_FORBIDDEN – Attempt to activate the limits for blocking conversions.
NRFX_ERROR_INVALID_STATE – Attempt to activate the limits without configured mode.

nrfx_err_t nrfx_saadc_offset_calibrate(nrfx_saadc_event_handler_t calib_event_handler)

Function for starting the SAADC offset calibration.

Parameters:

calib_event_handler – [in] Calibration event handler provided by the user. In case of providing NULL, the calibration will be performed in the blocking manner.

Return values:

NRFX_SUCCESS – Calibration finished successfully in the blocking manner or started successfully in the non-blocking manner.
NRFX_ERROR_BUSY – There is a conversion or calibration ongoing.

struct nrfx_saadc_channel_t

#include <nrfx_saadc.h>

SAADC channel configuration structure.

Public Members

nrf_saadc_channel_config_t channel_config: Channel hardware configuration.

nrf_saadc_input_t pin_p: Input positive pin selection.

nrf_saadc_input_t pin_n: Input negative pin selection.

uint8_t channel_index: Channel index.

struct nrfx_saadc_adv_config_t

#include <nrfx_saadc.h>

SAADC driver advanced mode configuration structure.

Public Members

nrf_saadc_oversample_t oversampling: Oversampling configuration.

nrf_saadc_burst_t burst: Burst configuration.

uint16_t internal_timer_cc: Internal timer capture and compare value.

bool start_on_end: Flag indicating if the START task is to be triggered on the END event.

struct nrfx_saadc_done_evt_t

#include <nrfx_saadc.h>

SAADC driver done event data.

Public Members

nrf_saadc_value_t *p_buffer: Pointer to the buffer with converted samples.

uint16_t size: Number of samples in the buffer.

struct nrfx_saadc_limit_evt_t

#include <nrfx_saadc.h>

SAADC driver limit event data.

Public Members

uint8_t channel: Channel on which the limit was detected.

nrf_saadc_limit_t limit_type: Type of limit detected.

struct nrfx_saadc_evt_t

#include <nrfx_saadc.h>

SAADC driver event structure.

Public Members

nrfx_saadc_evt_type_t type: Event type.

nrfx_saadc_done_evt_t done: Data for NRFX_SAADC_EVT_DONE event.

nrfx_saadc_limit_evt_t limit: Data for NRFX_SAADC_EVT_LIMIT event.

union nrfx_saadc_evt_t.[anonymous] data: Union to store event data.