Base class for a client of ADC. More...

#include <nrfcxx/periph.hpp>

Inheritance diagram for nrfcxx::periph::ADCClient:

Public Types
using	flags_type = unsigned int
	Type for client-specific flags.

using	queued_callback_type = std::function< void(int rc)>
	Signature for application notification of completed queue operation. More...

using	peripheral = ADC::peripheral

using	mutex_type = peripheral::mutex_type
	Mutex required to inhibit ADC interrupts.

Public Member Functions
virtual	~ADCClient ()
	Release the peripheral when the client is destructed.

int	claim ()
	Attempt to claim exclusive use of the ADC peripheral. More...

int	release ()
	Release the ADC peripheral. More...

int	calibrate (const notifier_type &notify={})
	Calibrate the ADC. More...

virtual int	sample_setup ()
	Overridable function to set up for an ADC measurement. More...

virtual void	sample_teardown ()
	Reverse the effects of sample_setup_(). More...

int	sample (const notifier_type &notify={})
	Trigger a client-specific collection. More...

int	queue (const notifier_type &notify, const queued_callback_type &qnotify={}, bool calibrate=false)
	Queue an operation to be initiated as soon as the ADC becomes available. More...

int	queue (bool calibrate=false)
	Overload when no notifications are required. More...

Protected Types
enum	flags_e : flags_type { FL_QUEUED_SAMPLE = 0x0001, FL_QUEUED_CALIBRATE = 0x0002, FL_QUEUED_Msk = FL_QUEUED_SAMPLE \| FL_QUEUED_CALIBRATE, FL_SUBCLASS_BASE = 0x0010 }
	Defined values for flags. More...

Protected Member Functions
int	sample_bi_ (const notifier_type &notify)
	Implements sample() given that the mutex is already held.

void	complete_queue_bi_ ()

virtual int	configure_bi_ ()
	Method to be invoked to configure the ADC for the next collection. More...

virtual void	complete_bi_ ()
	Method invoked when the collection completes. More...

virtual int	nrf51_next_bi_ (size_t ci)
	Function used to reconfigure ADC for next sample within the collection. More...

Static Protected Member Functions
static void	process_queue_bi_ ()

Protected Attributes
flags_type	flags_ = 0
	Flags for use by the core infrastructure and client specifications. More...

Friends
class	ADC

Detailed Description

Base class for a client of ADC.

This class supports shared use of the ADC peripheral. To make use of it, applications must provide infrastructure, configuration, and calibration as documented at ADC::irq_handler.

Much of the complexity of handling one-shot ADC collections may be delegated to sensor::adc::lpsm_wrapper.

Available implementations include:

nrfcxx::sensor::adc::vdd to measure the device voltage;
nrfcxx::sensor::adc::voltage_divider to measure an external voltage or variable-resistance sensor;
nrfcxx::sensor::adc::ntcThermistor to measure temperature with an NTC thermistor.

Member Typedef Documentation

◆ queued_callback_type

using nrfcxx::periph::ADCClient::queued_callback_type = std::function<void(int rc)>

Signature for application notification of completed queue operation.

Warning: Queue result callbacks are invoked with mutex_type held, commonly from within the ADC FLIH.

Parameters

rc	the result from the queued ADCClient::calibrate() or ADCClient::sample() request executed when the client reaches the front of the queue.

Member Enumeration Documentation

◆ flags_e

enum nrfcxx::periph::ADCClient::flags_e : flags_type

protected

Defined values for flags.

Enumerator
FL_QUEUED_SAMPLE	Bit set in flags_ when the client is queued to invoke sample().
FL_QUEUED_CALIBRATE	Bit set in flags_ when the client is queued to invoke calibrate().
FL_QUEUED_Msk	Mask to isolate queue state flags().
FL_SUBCLASS_BASE	Base for subclass use of flags_.

Member Function Documentation

◆ calibrate()

int nrfcxx::periph::ADCClient::calibrate ( const notifier_type & notify = {} )

inline

Calibrate the ADC.

This is a no-op on nRF51 devices which do not support/require calibration.

On nRF52 devices calibrate() should be invoked prior to first use and whenever the processor temperature changes by more than 10 Cel. Calibration is performed by first invoking configure_bi(), which is expected to set up SAADC channel zero: acquisition time and oversampling configurations affect the calibration.

Parameters

notify a callback to be invoked when calibration completes, either immediately or sometime in the future. The callback is not invoked if this function returns an error.

Returns: zero if calibration completes immediately, positive if the calibration has been initiated, or a negative error code.

◆ claim()

int nrfcxx::periph::ADCClient::claim ( )

inline

Attempt to claim exclusive use of the ADC peripheral.

Returns: zero on success, or a negative error code.

◆ complete_bi_()

virtual void nrfcxx::periph::ADCClient::complete_bi_ ( )

inlineprotectedvirtual

Method invoked when the collection completes.

Subclasses may implement this to support per-client callbacks that provide post-processed results from the collection. Classes may also update state and invoke sample_bi_(). For queued collections if the state remains claimed on completion of this call the client releases the ADC and processes the remainder of the queue.

This method is invoked prior to any per-sample callback installed by the client.

◆ configure_bi_()

virtual int nrfcxx::periph::ADCClient::configure_bi_ ( )

inlineprotectedvirtual

Method to be invoked to configure the ADC for the next collection.

Subclasses should use this to set up the configuration registers in the available ADC peripheral and provide a place in memory into which normalized ADC results will be written.

This method is invoked from calibrate() and for each sample().

Note: For SAADC clients this should ensure that SAADC->CH[0].CONFIG is set up with the desired acquisition time.

Returns: as with configure()

◆ nrf51_next_bi_()

virtual int nrfcxx::periph::ADCClient::nrf51_next_bi_ ( size_t ci )

inlineprotectedvirtual

Function used to reconfigure ADC for next sample within the collection.

This is used to simulate the nRF52's multi-channel ADC on the nRF51 by allowing a client to provide a new CONFIG register value that selects another channel.

If not overridden only single-channel collections will work on nRF51.

Parameters

ci	the channel index next to be collected.

Returns: a non-negative value to be used in the nrf5::ADC CONFIG register, or a negative value to indicate that collection has completed.

◆ queue() [1/2]

int nrfcxx::periph::ADCClient::queue ( bool calibrate = false )

inline

Overload when no notifications are required.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ queue() [2/2]

int nrfcxx::periph::ADCClient::queue	(	const notifier_type &	notify,
		const queued_callback_type &	qnotify = `{}`,
		bool	calibrate = `false`
	)

Queue an operation to be initiated as soon as the ADC becomes available.

This capability allows multiple ADC clients to be scheduled simultaneously (e.g. at a fixed interval) while not requiring the application to manage the claim, initiate, release notifications directly.

Invoking this method causes this client to be added to a FIFO queue of operations. As soon as the ADC is available—which may be during the invocation of this method—the claim() method is invoked and, if successful, either sample() or calibrate() is invoked. The result of these two operations may be provided to the application through qnotify. When the operation is complete release() is invoked and the next queued operation processed.

Note: A client can appear within the queue only once. Attempts to queue the client while it is in the queue, or while it is running after reaching the head of the queue, will be rejected. A client that has to perform multiple samples may delay release() by invoking sample_bi_() from within complete_bi_().

Warning: Both qnotify and notify are invoked with mutex_type held, generally from the ADC FLIH.

Parameters

notify	the notification callback to be passed to sample() or calibrate().
qnotify	function invoked when the requested operation is initiated, to provide the status of the initiation attempt to the application. Since the operation is invoked only when it is known that the ADC is available the implicit claim() and the sample()/calibrate() operation will both succeed and parameter should always indicate success.
calibrate	if `true` the queued operation invokes calibrate(); if `false` (default) the queued operation invokes sample().

Returns: zero on success, or a negative error code if the operation could not be queued.

◆ release()

int nrfcxx::periph::ADCClient::release ( )

inline

Release the ADC peripheral.

Returns: zero on success, or a negative error code.

◆ sample()

int nrfcxx::periph::ADCClient::sample ( const notifier_type & notify = {} )

inline

Trigger a client-specific collection.

Note: To initiate a sample when mutex_type is already held use sample_bi_().

Parameters

notify a callback to be invoked when collection completes. The callback is not invoked if this function returns an error. The callback is invoked after client-specific post-collection processing via ADCClient::complete_bi_().

Returns: positive if sampling has been initiated, or a negative error code.

◆ sample_setup()

virtual int nrfcxx::periph::ADCClient::sample_setup ( )

inlinevirtual

Overridable function to set up for an ADC measurement.

This might be used to enable current flow to a sensor that produces an analog output, such as a thermistor or photo transistor/resistor. In many cases there will be some delay before the sensor produces an accurate output; that delay is to be returned from this function.

Override of this method should be paired with an override of sample_teardown_().

The base class implementation does nothing and returns zero.

Note: It is the responsibility of the application to ensure this is invoked prior to any invocation of sample() or calibrate(), including through queue(), and that the component sample_teardown() is invoked after the ADC operations complete. This responsibility may be fulfilled through sensor::adc::lpsm_wrapper.

Returns: a delay in uptime ticks to wait before proceeding with the sample operation. If zero is returned the sample request may be initiated immediately after this function returns. A negative return may be used to indicate that sampling cannot be performed.

◆ sample_teardown()

virtual void nrfcxx::periph::ADCClient::sample_teardown ( )

inlinevirtual

Reverse the effects of sample_setup_().

For example, turn off the power flow to the analog sensor.

Field Documentation

◆ flags_

flags_type nrfcxx::periph::ADCClient::flags_ = 0

protected

Flags for use by the core infrastructure and client specifications.

Bits below FL_SUBCLASS_BASE are not to be touched by subclasses.

All manipulations of this field must be performed under mutex.

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

nrfcxx/periph.hpp

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ queued_callback_type

Member Enumeration Documentation

◆ flags_e

Member Function Documentation

◆ calibrate()

◆ claim()

◆ complete_bi_()

◆ configure_bi_()

◆ nrf51_next_bi_()

◆ queue() [1/2]

◆ queue() [2/2]

◆ release()

◆ sample()

◆ sample_setup()

◆ sample_teardown()

Field Documentation

◆ flags_