A continuous sampler over one or more analog pins. More...

Classes
struct	config
	Configuration for a continuous sampler. More...

struct	sample
	A single conversion result. More...

Public Member Functions
	sampler (config config)
	Constructs a continuous sampler.

	~sampler ()
	Destroys the sampler, stopping conversion and releasing ADC1.

	sampler (const sampler &)=delete

sampler &	operator= (const sampler &)=delete

	sampler (sampler &&other) noexcept

sampler &	operator= (sampler &&other) noexcept

std::span< const idfxx::gpio >	pins () const noexcept
	Returns the configured pins in conversion order.

enum attenuation	attenuation () const noexcept
	Returns the configured input-range attenuation (uniform across all pins).

freq::hertz	sample_rate () const noexcept
	Returns the configured total sample rate across all pins.

bool	running () const noexcept
	Returns true while the sampler is started.

bool	calibrated () const noexcept
	Returns true when factory calibration is active for every configured pin.

size_t	overruns () const noexcept
	Returns the number of dropped-data events since the last start.

void	start ()
	Starts continuous conversion.

void	stop ()
	Stops continuous conversion.

result< void >	try_start ()
	Starts continuous conversion.

result< void >	try_stop ()
	Stops continuous conversion.

size_t	read (std::span< sample > out)
	Reads samples, blocking until at least one is available.

template<typename Rep , typename Period >
size_t	read (std::span< sample > out, const std::chrono::duration< Rep, Period > &timeout)
	Reads samples, blocking until at least one is available or the timeout expires.

size_t	read (std::span< electro::millivolts > out)
	Reads samples as calibrated voltages, blocking until at least one is available.

template<typename Rep , typename Period >
size_t	read (std::span< electro::millivolts > out, const std::chrono::duration< Rep, Period > &timeout)
	Reads samples as calibrated voltages, blocking until at least one is available or the timeout expires.

result< size_t >	try_read (std::span< sample > out)
	Reads samples, blocking until at least one is available.

template<typename Rep , typename Period >
result< size_t >	try_read (std::span< sample > out, const std::chrono::duration< Rep, Period > &timeout)
	Reads samples, blocking until at least one is available or the timeout expires.

result< size_t >	try_read (std::span< electro::millivolts > out)
	Reads samples as calibrated voltages, blocking until at least one is available.

template<typename Rep , typename Period >
result< size_t >	try_read (std::span< electro::millivolts > out, const std::chrono::duration< Rep, Period > &timeout)
	Reads samples as calibrated voltages, blocking until at least one is available or the timeout expires.

electro::millivolts	to_voltage (const sample &s) const
	Converts a sample to a voltage using factory calibration.

electro::millivolts	to_voltage (int raw) const
	Converts a raw conversion value from a single-pin sampler to a voltage.

void	to_voltage (std::span< const sample > in, std::span< electro::millivolts > out) const
	Converts a batch of samples to voltages using factory calibration.

result< electro::millivolts >	try_to_voltage (const sample &s) const
	Converts a sample to a voltage using factory calibration.

result< electro::millivolts >	try_to_voltage (int raw) const
	Converts a raw conversion value from a single-pin sampler to a voltage.

result< void >	try_to_voltage (std::span< const sample > in, std::span< electro::millivolts > out) const
	Converts a batch of samples to voltages using factory calibration.

Static Public Member Functions
static result< sampler >	make (config config)
	Creates a continuous sampler.

Detailed Description

A continuous sampler over one or more analog pins.

Converts the configured pins round-robin at a fixed total rate and buffers the results internally; readers drain them with read / try_read. Claims the pins' ADC unit (ADC1) for the lifetime of the object. Move-only.

using namespace frequency_literals;
 
idfxx::adc::sampler mic({.pins = {idfxx::gpio_3}, .sample_rate = 20_kHz});
mic.start();
 
std::array<idfxx::adc::sampler::sample, 256> buf;
size_t n = mic.read(buf);
for (size_t i = 0; i < n; ++i) {
    electro::millivolts v = mic.to_voltage(buf[i]);
    // ...
}

Definition at line 234 of file adc.hpp.

Constructor & Destructor Documentation

◆ sampler() [1/3]

idfxx::adc::sampler::sampler ( config config )

explicit

Constructs a continuous sampler.

Resolves each pin's ADC channel, claims ADC1, configures the digital controller for round-robin conversion, and sets up factory calibration when the chip provides it. Sampling does not begin until start.

Parameters

config Sampler configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure (e.g. a pin is not ADC1-capable, the pin list is empty or has duplicates, or the sizes/rate are invalid).

◆ ~sampler()

idfxx::adc::sampler::~sampler ( )

Destroys the sampler, stopping conversion and releasing ADC1.

◆ sampler() [2/3]

idfxx::adc::sampler::sampler ( const sampler & )

delete

◆ sampler() [3/3]

idfxx::adc::sampler::sampler ( sampler && other )

noexcept

Member Function Documentation

◆ attenuation()

enum attenuation idfxx::adc::sampler::attenuation ( ) const

noexcept

Returns the configured input-range attenuation (uniform across all pins).

◆ calibrated()

bool idfxx::adc::sampler::calibrated ( ) const

noexcept

Returns true when factory calibration is active for every configured pin.

◆ make()

static result< sampler > idfxx::adc::sampler::make ( config config )

static

Creates a continuous sampler.

Resolves each pin's ADC channel, claims ADC1, configures the digital controller for round-robin conversion, and sets up factory calibration when the chip provides it. Sampling does not begin until try_start.

Parameters

config Sampler configuration.

Returns: The sampler, or an error.

Return values

idfxx::errc::invalid_arg The pin list is empty, exceeds the chip's conversion-pattern length, contains duplicates or unconnected pins, or a pin is not ADC1-capable; or frame_samples is zero, buffer_samples is smaller than frame_samples, or sample_rate is not positive.

◆ operator=() [1/2]

sampler & idfxx::adc::sampler::operator= ( const sampler & )

delete

◆ operator=() [2/2]

sampler & idfxx::adc::sampler::operator= ( sampler && other )

noexcept

◆ overruns()

size_t idfxx::adc::sampler::overruns ( ) const

noexcept

Returns the number of dropped-data events since the last start.

Increments each time the internal pool overflows because samples were not read fast enough; the samples produced while the pool was full are lost. Reset to zero by start / try_start.

Returns: Cumulative overrun count since the sampler was last started.

◆ pins()

std::span< const idfxx::gpio > idfxx::adc::sampler::pins ( ) const

noexcept

Returns the configured pins in conversion order.

◆ read() [1/4]

size_t idfxx::adc::sampler::read ( std::span< electro::millivolts > out )

inline

Reads samples as calibrated voltages, blocking until at least one is available.

Convenience for the single-pin case: reads and converts in one call, writing calibrated voltages in conversion order. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

For a multi-pin sampler the source pin of each voltage cannot be recovered from out; read with read(std::span<sample>) and convert with to_voltage to keep the association.

Parameters

out	Destination for the voltages (must not be empty).

Returns: The number of voltages written to out (always at least 1).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::invalid_state if the sampler is not running, idfxx::errc::invalid_arg if out is empty, or idfxx::errc::not_supported if a sampled pin has no usable calibration data (check calibrated).

Definition at line 445 of file adc.hpp.

References try_read(), and idfxx::unwrap().

◆ read() [2/4]

template<typename Rep , typename Period >

size_t idfxx::adc::sampler::read	(	std::span< electro::millivolts >	out,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Reads samples as calibrated voltages, blocking until at least one is available or the timeout expires.

Convenience for the single-pin case: reads and converts in one call, writing calibrated voltages in conversion order. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

out	Destination for the voltages (must not be empty).
timeout	Maximum time to wait for a sample.

Returns: The number of voltages written to out (always at least 1).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::timeout if no sample arrived within the timeout, idfxx::errc::invalid_state if the sampler is not running, or idfxx::errc::not_supported if a sampled pin has no usable calibration data.

Definition at line 466 of file adc.hpp.

References idfxx::timeout, try_read(), and idfxx::unwrap().

◆ read() [3/4]

size_t idfxx::adc::sampler::read ( std::span< sample > out )

inline

Reads samples, blocking until at least one is available.

Fills out with parsed samples in conversion order, tagging each with its source pin. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

Parameters

out	Destination for the samples (must not be empty).

Returns: The number of samples written to out (always at least 1).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::invalid_state if the sampler is not running, or idfxx::errc::invalid_arg if out is empty.

Definition at line 404 of file adc.hpp.

References try_read(), and idfxx::unwrap().

◆ read() [4/4]

template<typename Rep , typename Period >

size_t idfxx::adc::sampler::read	(	std::span< sample >	out,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Reads samples, blocking until at least one is available or the timeout expires.

Fills out with parsed samples in conversion order, tagging each with its source pin. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

out	Destination for the samples (must not be empty).
timeout	Maximum time to wait for a sample.

Returns: The number of samples written to out (always at least 1).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::timeout if no sample arrived within the timeout, or idfxx::errc::invalid_state if the sampler is not running.

Definition at line 424 of file adc.hpp.

References idfxx::timeout, try_read(), and idfxx::unwrap().

◆ running()

bool idfxx::adc::sampler::running ( ) const

noexcept

Returns true while the sampler is started.

◆ sample_rate()

freq::hertz idfxx::adc::sampler::sample_rate ( ) const

noexcept

Returns the configured total sample rate across all pins.

◆ start()

void idfxx::adc::sampler::start ( )

inline

Starts continuous conversion.

Resets overruns to zero. Samples accumulate in the internal pool from this point and are drained with read.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::invalid_state if already running, or on driver failure.

Definition at line 355 of file adc.hpp.

References try_start(), and idfxx::unwrap().

◆ stop()

void idfxx::adc::sampler::stop ( )

inline

Stops continuous conversion.

Idempotent: stopping a sampler that is not running has no effect.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on driver failure.

Definition at line 365 of file adc.hpp.

References try_stop(), and idfxx::unwrap().

◆ to_voltage() [1/3]

electro::millivolts idfxx::adc::sampler::to_voltage ( const sample & s ) const

inline

Converts a sample to a voltage using factory calibration.

Parameters

s	A sample previously produced by this sampler.

Returns: The calibrated voltage at the pin.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::invalid_arg if the sample's pin is not one of this sampler's configured pins, or idfxx::errc::not_supported if the chip has no usable calibration data (check calibrated).

Definition at line 565 of file adc.hpp.

References try_to_voltage(), and idfxx::unwrap().

◆ to_voltage() [2/3]

electro::millivolts idfxx::adc::sampler::to_voltage ( int raw ) const

inline

Converts a raw conversion value from a single-pin sampler to a voltage.

Convenience for samplers configured with exactly one pin, where the pin association is unambiguous — converts values computed from raw samples (a minimum, maximum, or mean) without fabricating a sample.

Parameters

raw	Raw conversion value (as in sample::raw).

Returns: The calibrated voltage at the sampler's pin.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::invalid_state if the sampler is configured with more than one pin, or idfxx::errc::not_supported if the chip has no usable calibration data (check calibrated).

Definition at line 582 of file adc.hpp.

References try_to_voltage(), and idfxx::unwrap().

◆ to_voltage() [3/3]

void idfxx::adc::sampler::to_voltage	(	std::span< const sample >	in,
		std::span< electro::millivolts >	out
	)		const

inline

Converts a batch of samples to voltages using factory calibration.

Writes out[i] as the calibrated voltage of in[i], preserving order and pin association. Resolves each pin's calibration once per run of like-pinned samples, so converting a whole read is cheaper than calling to_voltage(const sample&) per element.

Parameters

in	Samples previously produced by this sampler.
out	Destination for the voltages; must be at least as large as `in`.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::invalid_arg if out is smaller than in or a sample's pin is not one of this sampler's configured pins, or idfxx::errc::not_supported if a pin has no usable calibration data (check calibrated).

Definition at line 599 of file adc.hpp.

References try_to_voltage(), and idfxx::unwrap().

◆ try_read() [1/4]

result< size_t > idfxx::adc::sampler::try_read ( std::span< electro::millivolts > out )

inline

Reads samples as calibrated voltages, blocking until at least one is available.

Convenience for the single-pin case: reads and converts in one call, writing calibrated voltages in conversion order. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

For a multi-pin sampler the source pin of each voltage cannot be recovered from out; read with try_read(std::span<sample>) and convert with try_to_voltage to keep the association.

Parameters

out	Destination for the voltages (must not be empty).

Returns: The number of voltages written to out (always at least 1), or an error.

Return values

idfxx::errc::invalid_state	The sampler is not running.
idfxx::errc::invalid_arg	`out` is empty.
idfxx::errc::not_supported	A sampled pin has no usable calibration data (check calibrated).

Definition at line 526 of file adc.hpp.

◆ try_read() [2/4]

template<typename Rep , typename Period >

result< size_t > idfxx::adc::sampler::try_read	(	std::span< electro::millivolts >	out,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Reads samples as calibrated voltages, blocking until at least one is available or the timeout expires.

Convenience for the single-pin case: reads and converts in one call, writing calibrated voltages in conversion order. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

out	Destination for the voltages (must not be empty).
timeout	Maximum time to wait for a sample.

Returns: The number of voltages written to out (always at least 1), or an error.

Return values

idfxx::errc::timeout	No sample arrived within the timeout.
idfxx::errc::invalid_state	The sampler is not running.
idfxx::errc::not_supported	A sampled pin has no usable calibration data.

Definition at line 549 of file adc.hpp.

References idfxx::timeout.

◆ try_read() [3/4]

result< size_t > idfxx::adc::sampler::try_read ( std::span< sample > out )

inline

Reads samples, blocking until at least one is available.

Fills out with parsed samples in conversion order, tagging each with its source pin. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

Parameters

out	Destination for the samples (must not be empty).

Returns: The number of samples written to out (always at least 1), or an error.

Return values

idfxx::errc::invalid_state	The sampler is not running.
idfxx::errc::invalid_arg	`out` is empty.

Definition at line 484 of file adc.hpp.

Referenced by read(), read(), read(), and read().

◆ try_read() [4/4]

template<typename Rep , typename Period >

result< size_t > idfxx::adc::sampler::try_read	(	std::span< sample >	out,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Reads samples, blocking until at least one is available or the timeout expires.

Fills out with parsed samples in conversion order, tagging each with its source pin. Returns as soon as at least one sample is available; it does not wait to fill the entire span.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

out	Destination for the samples (must not be empty).
timeout	Maximum time to wait for a sample.

Returns: The number of samples written to out (always at least 1), or an error.

Return values

idfxx::errc::timeout	No sample arrived within the timeout.
idfxx::errc::invalid_state	The sampler is not running.
idfxx::errc::invalid_arg	`out` is empty.

Definition at line 504 of file adc.hpp.

References idfxx::timeout.

◆ try_start()

result< void > idfxx::adc::sampler::try_start ( )

Starts continuous conversion.

Resets overruns to zero. Samples accumulate in the internal pool from this point and are drained with try_read.

Returns: Success, or an error.

Return values

idfxx::errc::invalid_state The sampler is already running.

Referenced by start().

◆ try_stop()

result< void > idfxx::adc::sampler::try_stop ( )

Stops continuous conversion.

Idempotent: stopping a sampler that is not running succeeds with no effect.

Returns: Success, or an error.

Referenced by stop().

◆ try_to_voltage() [1/3]

result< electro::millivolts > idfxx::adc::sampler::try_to_voltage ( const sample & s ) const

Converts a sample to a voltage using factory calibration.

Parameters

s	A sample previously produced by this sampler.

Returns: The calibrated voltage at the pin, or an error.

Return values

idfxx::errc::invalid_arg	The sample's pin is not one of this sampler's configured pins.
idfxx::errc::not_supported	The chip has no usable calibration data (check calibrated).

Referenced by to_voltage(), to_voltage(), and to_voltage().

◆ try_to_voltage() [2/3]

result< electro::millivolts > idfxx::adc::sampler::try_to_voltage ( int raw ) const

Converts a raw conversion value from a single-pin sampler to a voltage.

Convenience for samplers configured with exactly one pin, where the pin association is unambiguous.

Parameters

raw	Raw conversion value (as in sample::raw).

Returns: The calibrated voltage at the sampler's pin, or an error.

Return values

idfxx::errc::invalid_state	The sampler is configured with more than one pin.
idfxx::errc::not_supported	The chip has no usable calibration data (check calibrated).

◆ try_to_voltage() [3/3]

result< void > idfxx::adc::sampler::try_to_voltage	(	std::span< const sample >	in,
		std::span< electro::millivolts >	out
	)		const

Converts a batch of samples to voltages using factory calibration.

Writes out[i] as the calibrated voltage of in[i], preserving order and pin association.

Parameters

in	Samples previously produced by this sampler.
out	Destination for the voltages; must be at least as large as `in`.

Returns: Success, or an error.

Return values

idfxx::errc::invalid_arg	`out` is smaller than `in`, or a sample's pin is not one of this sampler's configured pins.
idfxx::errc::not_supported	A pin has no usable calibration data (check calibrated).

The documentation for this class was generated from the following file:

idfxx_adc/include/idfxx/adc.hpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ sampler() [1/3]

◆ ~sampler()

◆ sampler() [2/3]

◆ sampler() [3/3]

Member Function Documentation

◆ attenuation()

◆ calibrated()

◆ make()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ overruns()

◆ pins()

◆ read() [1/4]

◆ read() [2/4]

◆ read() [3/4]

◆ read() [4/4]

◆ running()

◆ sample_rate()

◆ start()

◆ stop()

◆ to_voltage() [1/3]

◆ to_voltage() [2/3]

◆ to_voltage() [3/3]

◆ try_read() [1/4]

◆ try_read() [2/4]

◆ try_read() [3/4]

◆ try_read() [4/4]

◆ try_start()

◆ try_stop()

◆ try_to_voltage() [1/3]

◆ try_to_voltage() [2/3]

◆ try_to_voltage() [3/3]