Analog-to-Digital Converter (ADC)

Overview

API Reference

group adc_interface

ADC driver APIs.

Defines

ADC_CHANNEL_CFG_DT(node_id)

Get ADC channel configuration from a given devicetree node.

This returns a static initializer for a struct adc_channel_cfg filled with data from a given devicetree node.

Example devicetree fragment:

&adc {
   #address-cells = <1>;
   #size-cells = <0>;

   channel@0 {
       reg = <0>;
       zephyr,gain = "ADC_GAIN_1_6";
       zephyr,reference = "ADC_REF_INTERNAL";
       zephyr,acquisition-time = <ADC_ACQ_TIME(ADC_ACQ_TIME_MICROSECONDS, 20)>;
       zephyr,input-positive = <NRF_SAADC_AIN6>;
       zephyr,input-negative = <NRF_SAADC_AIN7>;
   };

   channel@1 {
       reg = <1>;
       zephyr,gain = "ADC_GAIN_1_6";
       zephyr,reference = "ADC_REF_INTERNAL";
       zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
       zephyr,input-positive = <NRF_SAADC_AIN0>;
   };
};

Example usage:

static const struct adc_channel_cfg ch0_cfg_dt =
    ADC_CHANNEL_CFG_DT(DT_CHILD(DT_NODELABEL(adc), channel_0));
static const struct adc_channel_cfg ch1_cfg_dt =
    ADC_CHANNEL_CFG_DT(DT_CHILD(DT_NODELABEL(adc), channel_1));

// Initializes 'ch0_cfg_dt' to:
// {
//     .channel_id = 0,
//     .gain = ADC_GAIN_1_6,
//     .reference = ADC_REF_INTERNAL,
//     .acquisition_time = ADC_ACQ_TIME(ADC_ACQ_TIME_MICROSECONDS, 20),
//     .differential = true,
//     .input_positive = NRF_SAADC_AIN6,
//     .input-negative = NRF_SAADC_AIN7,
// }
// and 'ch1_cfg_dt' to:
// {
//     .channel_id = 1,
//     .gain = ADC_GAIN_1_6,
//     .reference = ADC_REF_INTERNAL,
//     .acquisition_time = ADC_ACQ_TIME_DEFAULT,
//     .input_positive = NRF_SAADC_AIN0,
// }

Parameters:

node_id – Devicetree node identifier.

Returns:

Static initializer for an adc_channel_cfg structure.

ADC_DT_SPEC_GET_BY_IDX(node_id, idx)

Get ADC io-channel information from devicetree.

This returns a static initializer for an adc_dt_spec structure given a devicetree node and a channel index. The node must have the “io-channels” property defined.

Example devicetree fragment:

/ {
    zephyr,user {
        io-channels = <&adc0 1>, <&adc0 3>;
    };
};

&adc0 {
   #address-cells = <1>;
   #size-cells = <0>;

   channel@3 {
       reg = <3>;
       zephyr,gain = "ADC_GAIN_1_5";
       zephyr,reference = "ADC_REF_VDD_1_4";
       zephyr,vref-mv = <750>;
       zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
       zephyr,resolution = <12>;
       zephyr,oversampling = <4>;
   };
};

Example usage:

static const struct adc_dt_spec adc_chan0 =
    ADC_DT_SPEC_GET_BY_IDX(DT_PATH(zephyr_user), 0);
static const struct adc_dt_spec adc_chan1 =
    ADC_DT_SPEC_GET_BY_IDX(DT_PATH(zephyr_user), 1);

// Initializes 'adc_chan0' to:
// {
//     .dev = DEVICE_DT_GET(DT_NODELABEL(adc0)),
//     .channel_id = 1,
// }
// and 'adc_chan1' to:
// {
//     .dev = DEVICE_DT_GET(DT_NODELABEL(adc0)),
//     .channel_id = 3,
//     .channel_cfg_dt_node_exists = true,
//     .channel_cfg = {
//         .channel_id = 3,
//         .gain = ADC_GAIN_1_5,
//         .reference = ADC_REF_VDD_1_4,
//         .acquisition_time = ADC_ACQ_TIME_DEFAULT,
//     },
//     .vref_mv = 750,
//     .resolution = 12,
//     .oversampling = 4,
// }

See also

ADC_DT_SPEC_GET()

Parameters:

node_id – Devicetree node identifier.
idx – Channel index.

Returns:

Static initializer for an adc_dt_spec structure.

ADC_DT_SPEC_INST_GET_BY_IDX(inst, idx)

Get ADC io-channel information from a DT_DRV_COMPAT devicetree instance.

See also

ADC_DT_SPEC_GET_BY_IDX()

Parameters:

inst – DT_DRV_COMPAT instance number
idx – Channel index.

Returns:

Static initializer for an adc_dt_spec structure.

ADC_DT_SPEC_GET(node_id)

Equivalent to ADC_DT_SPEC_GET_BY_IDX(node_id, 0).

See also

ADC_DT_SPEC_GET_BY_IDX()

Parameters:

node_id – Devicetree node identifier.

Returns:

Static initializer for an adc_dt_spec structure.

ADC_DT_SPEC_INST_GET(inst)

Equivalent to ADC_DT_SPEC_INST_GET_BY_IDX(inst, 0).

See also

ADC_DT_SPEC_GET()

Parameters:

inst – DT_DRV_COMPAT instance number

Returns:

Static initializer for an adc_dt_spec structure.

Typedefs

typedef enum adc_action (*adc_sequence_callback)(const struct device *dev, const struct adc_sequence *sequence, uint16_t sampling_index)

Type definition of the optional callback function to be called after a requested sampling is done.

Param dev:: Pointer to the device structure for the driver instance.
Param sequence:: Pointer to the sequence structure that triggered the sampling. This parameter points to a copy of the structure that was supplied to the call that started the sampling sequence, thus it cannot be used with the CONTAINER_OF() macro to retrieve some other data associated with the sequence. Instead, the adc_sequence_options::user_data field should be used for such purpose.
Param sampling_index:: Index (0-65535) of the sampling done.
Return:: Action to be performed by the driver. See adc_action.

typedef int (*adc_api_channel_setup)(const struct device *dev, const struct adc_channel_cfg *channel_cfg)

Type definition of ADC API function for configuring a channel.

See adc_channel_setup() for argument descriptions.

typedef int (*adc_api_read)(const struct device *dev, const struct adc_sequence *sequence)

Type definition of ADC API function for setting a read request.

See adc_read() for argument descriptions.

typedef int (*adc_api_read_async)(const struct device *dev, const struct adc_sequence *sequence, struct k_poll_signal *async)

Type definition of ADC API function for setting an asynchronous read request.

See adc_read_async() for argument descriptions.

Enums

enum adc_gain

ADC channel gain factors.

Values:

enumerator ADC_GAIN_1_6: x 1/6.

enumerator ADC_GAIN_1_5: x 1/5.

enumerator ADC_GAIN_1_4: x 1/4.

enumerator ADC_GAIN_1_3: x 1/3.

enumerator ADC_GAIN_2_5: x 2/5.

enumerator ADC_GAIN_1_2: x 1/2.

enumerator ADC_GAIN_2_3: x 2/3.

enumerator ADC_GAIN_4_5: x 4/5.

enumerator ADC_GAIN_1: x 1.

enumerator ADC_GAIN_2: x 2.

enumerator ADC_GAIN_3: x 3.

enumerator ADC_GAIN_4: x 4.

enumerator ADC_GAIN_6: x 6.

enumerator ADC_GAIN_8: x 8.

enumerator ADC_GAIN_12: x 12.

enumerator ADC_GAIN_16: x 16.

enumerator ADC_GAIN_24: x 24.

enumerator ADC_GAIN_32: x 32.

enumerator ADC_GAIN_64: x 64.

enumerator ADC_GAIN_128: x 128.

enum adc_reference

ADC references.

Values:

enumerator ADC_REF_VDD_1: VDD.

enumerator ADC_REF_VDD_1_2: VDD/2.

enumerator ADC_REF_VDD_1_3: VDD/3.

enumerator ADC_REF_VDD_1_4: VDD/4.

enumerator ADC_REF_INTERNAL: Internal.

enumerator ADC_REF_EXTERNAL0: External, input 0.

enumerator ADC_REF_EXTERNAL1: External, input 1.

enum adc_action

Action to be performed after a sampling is done.

Values:

enumerator ADC_ACTION_CONTINUE = 0: The sequence should be continued normally.

enumerator ADC_ACTION_REPEAT

The sampling should be repeated.

New samples or sample should be read from the ADC and written in the same place as the recent ones.

enumerator ADC_ACTION_FINISH: The sequence should be finished immediately.

Functions

int adc_gain_invert(enum adc_gain gain, int32_t *value)

Invert the application of gain to a measurement value.

For example, if the gain passed in is ADC_GAIN_1_6 and the referenced value is 10, the value after the function returns is 60.

Parameters:

gain – the gain used to amplify the input signal.
value – a pointer to a value that initially has the effect of the applied gain but has that effect removed when this function successfully returns. If the gain cannot be reversed the value remains unchanged.

Return values:

0 – if the gain was successfully reversed
-EINVAL – if the gain could not be interpreted

int adc_channel_setup(const struct device *dev, const struct adc_channel_cfg *channel_cfg)

Configure an ADC channel.

It is required to call this function and configure each channel before it is selected for a read request.

Parameters:

dev – Pointer to the device structure for the driver instance.
channel_cfg – Channel configuration.

Return values:

0 – On success.
-EINVAL – If a parameter with an invalid value has been provided.

static inline int adc_channel_setup_dt(const struct adc_dt_spec *spec)

Configure an ADC channel from a struct adc_dt_spec.

See also

adc_channel_setup()

Parameters:

spec – ADC specification from Devicetree.

Returns:

A value from adc_channel_setup() or -ENOTSUP if information from Devicetree is not valid.

int adc_read(const struct device *dev, const struct adc_sequence *sequence)

Set a read request.

If invoked from user mode, any sequence struct options for callback must be NULL.

Parameters:

dev – Pointer to the device structure for the driver instance.
sequence – Structure specifying requested sequence of samplings.

Return values:

0 – On success.
-EINVAL – If a parameter with an invalid value has been provided.
-ENOMEM – If the provided buffer is to small to hold the results of all requested samplings.
-ENOTSUP – If the requested mode of operation is not supported.
-EBUSY – If another sampling was triggered while the previous one was still in progress. This may occur only when samplings are done with intervals, and it indicates that the selected interval was too small. All requested samples are written in the buffer, but at least some of them were taken with an extra delay compared to what was scheduled.

int adc_read_async(const struct device *dev, const struct adc_sequence *sequence, struct k_poll_signal *async)

Set an asynchronous read request.

If invoked from user mode, any sequence struct options for callback must be NULL.

Note

This function is available only if CONFIG_ADC_ASYNC is selected.

Parameters:

dev – Pointer to the device structure for the driver instance.
sequence – Structure specifying requested sequence of samplings.
async – Pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).

Returns:

0 on success, negative error code otherwise. See adc_read() for a list of possible error codes.

static inline uint16_t adc_ref_internal(const struct device *dev)

Get the internal reference voltage.

Returns the voltage corresponding to ADC_REF_INTERNAL, measured in millivolts.

Returns:: a positive value is the reference voltage value. Returns zero if reference voltage information is not available.

static inline int adc_raw_to_millivolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution, int32_t *valp)

Convert a raw ADC value to millivolts.

This function performs the necessary conversion to transform a raw ADC measurement to a voltage in millivolts.

Parameters:

ref_mv – the reference voltage used for the measurement, in millivolts. This may be from adc_ref_internal() or a known external reference.
gain – the ADC gain configuration used to sample the input
resolution – the number of bits in the absolute value of the sample. For differential sampling this needs to be one less than the resolution in struct adc_sequence.
valp – pointer to the raw measurement value on input, and the corresponding millivolt value on successful conversion. If conversion fails the stored value is left unchanged.

Return values:

0 – on successful conversion
-EINVAL – if the gain is not reversible

static inline int adc_raw_to_millivolts_dt(const struct adc_dt_spec *spec, int32_t *valp)

Convert a raw ADC value to millivolts using information stored in a struct adc_dt_spec.

See also

adc_raw_to_millivolts()

Parameters:

spec – [in] ADC specification from Devicetree.
valp – [inout] Pointer to the raw measurement value on input, and the corresponding millivolt value on successful conversion. If conversion fails the stored value is left unchanged.

Returns:

A value from adc_raw_to_millivolts() or -ENOTSUP if information from Devicetree is not valid.

static inline int adc_sequence_init_dt(const struct adc_dt_spec *spec, struct adc_sequence *seq)

Initialize a struct adc_sequence from information stored in struct adc_dt_spec.

Note that this function only initializes the following fields:

adc_sequence::channels
adc_sequence::resolution
adc_sequence::oversampling

Other fields should be initialized by the caller.

Parameters:

spec – [in] ADC specification from Devicetree.
seq – [out] Sequence to initialize.

Return values:

0 – On success
-ENOTSUP – If spec does not have valid channel configuration

static inline bool adc_is_ready_dt(const struct adc_dt_spec *spec)

Validate that the ADC device is ready.

Parameters:

spec – ADC specification from devicetree

Return values:

true – if the ADC device is ready for use and false otherwise.

struct adc_channel_cfg

#include <adc.h>

Structure for specifying the configuration of an ADC channel.

Public Members

enum adc_gain gain: Gain selection.

enum adc_reference reference: Reference selection.

uint16_t acquisition_time

Acquisition time.

Use the ADC_ACQ_TIME macro to compose the value for this field or pass ADC_ACQ_TIME_DEFAULT to use the default setting for a given hardware (e.g. when the hardware does not allow to configure the acquisition time). Particular drivers do not necessarily support all the possible units. Value range is 0-16383 for a given unit.

uint8_t channel_id

Channel identifier.

This value primarily identifies the channel within the ADC API - when a read request is done, the corresponding bit in the “channels” field of the “adc_sequence” structure must be set to include this channel in the sampling. For hardware that does not allow selection of analog inputs for given channels, but rather have dedicated ones, this value also selects the physical ADC input to be used in the sampling. Otherwise, when it is needed to explicitly select an analog input for the channel, or two inputs when the channel is a differential one, the selection is done in “input_positive” and “input_negative” fields. Particular drivers indicate which one of the above two cases they support by selecting or not a special hidden Kconfig option named ADC_CONFIGURABLE_INPUTS. If this option is not selected, the macro CONFIG_ADC_CONFIGURABLE_INPUTS is not defined and consequently the mentioned two fields are not present in this structure. While this API allows identifiers from range 0-31, particular drivers may support only a limited number of channel identifiers (dependent on the underlying hardware capabilities or configured via a dedicated Kconfig option).

uint8_t differential: Channel type: single-ended or differential.

struct adc_dt_spec

#include <adc.h>

Container for ADC channel information specified in devicetree.

See also

ADC_DT_SPEC_GET_BY_IDX

See also

ADC_DT_SPEC_GET

Public Members

const struct device *dev: Pointer to the device structure for the ADC driver instance used by this io-channel.

uint8_t channel_id: ADC channel identifier used by this io-channel.

bool channel_cfg_dt_node_exists: Flag indicating whether configuration of the associated ADC channel is provided as a child node of the corresponding ADC controller in devicetree.

struct adc_channel_cfg channel_cfg

Configuration of the associated ADC channel specified in devicetree.

This field is valid only when channel_cfg_dt_node_exists is set to true.

uint16_t vref_mv

Voltage of the reference selected for the channel or 0 if this value is not provided in devicetree.

This field is valid only when channel_cfg_dt_node_exists is set to true.

uint8_t resolution

ADC resolution to be used for that channel.

This field is valid only when channel_cfg_dt_node_exists is set to true.

uint8_t oversampling

Oversampling setting to be used for that channel.

This field is valid only when channel_cfg_dt_node_exists is set to true.

struct adc_sequence_options

#include <adc.h>

Structure defining additional options for an ADC sampling sequence.

Public Members

uint32_t interval_us

Interval between consecutive samplings (in microseconds), 0 means sample as fast as possible, without involving any timer.

The accuracy of this interval is dependent on the implementation of a given driver. The default routine that handles the intervals uses a kernel timer for this purpose, thus, it has the accuracy of the kernel’s system clock. Particular drivers may use some dedicated hardware timers and achieve a better precision.

adc_sequence_callback callback

Callback function to be called after each sampling is done.

Optional - set to NULL if it is not needed.

void *user_data

Pointer to user data.

It can be used to associate the sequence with any other data that is needed in the callback function.

uint16_t extra_samplings: Number of extra samplings to perform (the total number of samplings is 1 + extra_samplings).

struct adc_sequence

#include <adc.h>

Structure defining an ADC sampling sequence.

Public Members

const struct adc_sequence_options *options

Pointer to a structure defining additional options for the sequence.

If NULL, the sequence consists of a single sampling.

uint32_t channels

Bit-mask indicating the channels to be included in each sampling of this sequence.

All selected channels must be configured with adc_channel_setup() before they are used in a sequence. The least significant bit corresponds to channel 0.

void *buffer

Pointer to a buffer where the samples are to be written.

Samples from subsequent samplings are written sequentially in the buffer. The number of samples written for each sampling is determined by the number of channels selected in the “channels” field. The values written to the buffer represent a sample from each selected channel starting from the one with the lowest ID. The buffer must be of an appropriate size, taking into account the number of selected channels and the ADC resolution used, as well as the number of samplings contained in the sequence.

size_t buffer_size

Specifies the actual size of the buffer pointed by the “buffer” field (in bytes).

The driver must ensure that samples are not written beyond the limit and it must return an error if the buffer turns out to be not large enough to hold all the requested samples.

uint8_t resolution

ADC resolution.

For single-ended channels the sample values are from range: 0 .. 2^resolution - 1, for differential ones:

2^(resolution-1) .. 2^(resolution-1) - 1.

uint8_t oversampling

Oversampling setting.

Each sample is averaged from 2^oversampling conversion results. This feature may be unsupported by a given ADC hardware, or in a specific mode (e.g. when sampling multiple channels).

bool calibrate

Perform calibration before the reading is taken if requested.

The impact of channel configuration on the calibration process is specific to the underlying hardware. ADC implementations that do not support calibration should ignore this flag.

struct adc_driver_api

#include <adc.h>

ADC driver API.

This is the mandatory API any ADC driver needs to expose.