SAADC driver

group nrfx_saadc

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

Defines

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/6

  • reference voltage: internal 0.6 V

  • sample acquisition time: 10 us

  • burst disabled

See

nrfx_saadc_channel_t

Parameters

  • _pin_p – [in] Positive input analog pin.

  • _index – [in] Channel index.

NRFX_SAADC_DEFAULT_CHANNEL_DIFFERENTIAL(_pin_p, _pin_n, _index)

SAADC channel default configuration for the differential mode.

This configuration sets up differential SAADC channel with the following options:

  • resistor ladder disabled

  • gain: 1/6

  • reference voltage: internal 0.6 V

  • sample acquisition time: 10 us

  • burst disabled

See

nrfx_saadc_channel_t

Parameters

  • _pin_p – [in] Positive input analog pin.

  • _pin_n – [in] Negative input analog pin.

  • _index – [in] Channel index.

NRFX_SAADC_DEFAULT_ADV_CONFIG

SAADC driver advanced mode default configuration.

This configuration sets up advanced mode of the SAADC driver with the following options:

  • oversampling disabled

  • burst disabled

  • internal sampling timer disabled

  • triggering of the START task on the END event disabled

See

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:

Parameters

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

Returns NRFX_SUCCESS

Initialization was successful.

Returns NRFX_ERROR_INVALID_STATE

The driver is already initialized.

void nrfx_saadc_uninit(void)

Function for uninitializing the SAADC driver.

This function stops all ongoing conversions and disables all channels.

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.

Returns NRFX_SUCCESS

Configuration was successful.

Returns NRFX_ERROR_BUSY

There is a conversion or calibration ongoing.

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

Returns NRFX_SUCCESS

Configuration was successful.

Returns NRFX_ERROR_BUSY

There is a conversion or calibration ongoing.

nrfx_err_t nrfx_saadc_channels_deconfig(uint32_t channel_mask)

Function for deconfiguring the specified SAADC channels.

Parameters

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

Returns NRFX_SUCCESS

Deconfiguration was successful.

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

Returns NRFX_SUCCESS

Initialization was successful.

Returns NRFX_ERROR_BUSY

There is a conversion or calibration ongoing.

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

Returns NRFX_SUCCESS

Initialization was successful.

Returns NRFX_ERROR_BUSY

There is a conversion or calibration ongoing.

Returns NRFX_ERROR_INVALID_PARAM

Attempt to activate channel that is not configured.

Returns NRFX_ERROR_NOT_SUPPORTED

Attempt to activate internal timer or 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 nrf_saadc_value_t samples in buffer.

Returns NRFX_SUCCESS

Buffer was supplied successfully.

Returns NRFX_ERROR_INVALID_ADDR

The provided buffer is not in the Data RAM region.

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

Returns NRFX_ERROR_INVALID_STATE

The driver is in the idle mode.

Returns NRFX_ERROR_ALREADY_INITIALIZED

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.

Returns NRFX_SUCCESS

Operation finished successfully in the blocking manner or started successfully in the non-blocking manner.

Returns NRFX_ERROR_BUSY

The driver is performing the conversion in the advanced blocking mode. Call the function again to continue the conversion.

Returns NRFX_ERROR_NO_MEM

There is no buffer provided. Supply the buffer using nrfx_saadc_buffer_set() and try again.

Returns NRFX_ERROR_INVALID_STATE

There is an ongoing conversion 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.

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.

Returns NRFX_SUCCESS

Requested channel limits were set.

Returns NRFX_ERROR_INVALID_PARAM

Attempt to activate the limits on disabled channel.

Returns NRFX_ERROR_FORBIDDEN

Attempt to activate the limits for blocking conversions.

Returns NRFX_ERROR_INVALID_STATE

Attempt to activate the limits without configured mode.

nrfx_err_t nrfx_saadc_offset_calibrate(nrfx_saadc_event_handler_t event_handler)

Function for starting the SAADC offset calibration.

Note

This function cancels the currently selected driver operation mode, if any. The desired mode (simple or advanced) must be set after the calibration process completes.

Parameters

  • event_handler – [in] Event handler provided by the user. In case of providing NULL, the calibration will be performed in the blocking manner.

Returns NRFX_SUCCESS

Calibration finished successfully in the blocking manner or started successfully in the non-blocking manner.

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