Implements all functions of the Teensy 3.x, LC, 4.x analog to digital converter. More...

#include <ADC_Module.h>

Classes
struct	ADC_Config
	Store the config of the adc. More...

Public Member Functions
	ADC_Module (uint8_t ADC_number, const uint8_t const a_channel2sc1a, const ADC_NLIST const a_diff_table, ADC_REGS_t &a_adc_regs)
	Pass the ADC number and the Channel number to SC1A number arrays. More...

Calibration functions
void	recalibrate ()
	Starts the calibration sequence, waits until it's done and writes the results. More...

void	calibrate ()
	Starts the calibration sequence.

void	wait_for_cal ()
	Waits until calibration is finished and writes the corresponding registers.

ADC settings
void	setReference (ADC_REFERENCE ref_type)
	Set the voltage reference you prefer, default is vcc. More...

void	setResolution (uint8_t bits)
	Change the resolution of the measurement. More...

uint8_t	getResolution ()
	Returns the resolution of the ADC_Module. More...

uint32_t	getMaxValue ()
	Returns the maximum value for a measurement: 2^res-1. More...

void	setConversionSpeed (ADC_CONVERSION_SPEED speed)
	Sets the conversion speed (changes the ADC clock, ADCK) More...

void	setSamplingSpeed (ADC_SAMPLING_SPEED speed)
	Sets the sampling speed. More...

void	setAveraging (uint8_t num)
	Set the number of averages. More...

void	enableInterrupts (void(*isr)(void), uint8_t priority=255)
	Enable interrupts. More...

void	disableInterrupts ()
	Disable interrupts.

void	enableDMA ()
	Enable DMA request. More...

void	disableDMA ()
	Disable ADC DMA request.

void	enableCompare (int16_t compValue, bool greaterThan)
	Enable the compare function to a single value. More...

void	enableCompareRange (int16_t lowerLimit, int16_t upperLimit, bool insideRange, bool inclusive)
	Enable the compare function to a range. More...

void	disableCompare ()
	Disable the compare function.

void	enablePGA (uint8_t gain)
	Enables the PGA and sets the gain. More...

uint8_t	getPGA ()
	Returns the PGA level. More...

void	disablePGA ()
	Disable PGA.

void	continuousMode ()
	Set continuous conversion mode.

void	singleMode ()
	Set single-shot conversion mode.

void	singleEndedMode ()
	Set single-ended conversion mode.

void	differentialMode ()
	Set differential conversion mode.

void	setSoftwareTrigger ()
	Use software to trigger the ADC, this is the most common setting.

void	setHardwareTrigger ()
	Use hardware to trigger the ADC.

State of the ADC
volatile bool	isConverting ()
	Is the ADC converting at the moment? More...

volatile bool	isComplete ()
	Is an ADC conversion ready? More...

volatile bool	isDifferential ()
	Is the ADC in differential mode? More...

volatile bool	isContinuous ()
	Is the ADC in continuous mode? More...

volatile bool	isPGAEnabled ()
	Is the PGA function enabled? More...

Valid pins
bool	checkPin (uint8_t pin)
	Check whether the pin is a valid analog pin. More...

bool	checkDifferentialPins (uint8_t pinP, uint8_t pinN)
	Check whether the pins are a valid analog differential pair of pins. More...

Conversion helper methods
void	startReadFast (uint8_t pin)
	Starts a single-ended conversion on the pin. More...

void	startDifferentialFast (uint8_t pinP, uint8_t pinN)
	Starts a differential conversion on the pair of pins. More...

Blocking conversion methods
int	analogRead (uint8_t pin)
	Returns the analog value of the pin. More...

int	analogRead (ADC_INTERNAL_SOURCE pin)
	Returns the analog value of the special internal source, such as the temperature sensor. More...

int	analogReadDifferential (uint8_t pinP, uint8_t pinN)
	Reads the differential analog value of two pins (pinP - pinN). More...

Non-blocking conversion methods
bool	startSingleRead (uint8_t pin)
	Starts an analog measurement on the pin. It returns immediately, get value with readSingle(). If this function interrupts a measurement, it stores the settings in adc_config. More...

bool	startSingleDifferential (uint8_t pinP, uint8_t pinN)
	Start a differential conversion between two pins (pinP - pinN) It returns immediately, get value with readSingle(). If this function interrupts a measurement, it stores the settings in adc_config. More...

int	readSingle ()
	Reads the analog value of a single conversion. Set the conversion with with startSingleRead(uint8_t pin) or startSingleDifferential(uint8_t pinP, uint8_t pinN). More...

Continuous conversion methods
bool	startContinuous (uint8_t pin)
	Starts continuous conversion on the pin. More...

bool	startContinuousDifferential (uint8_t pinP, uint8_t pinN)
	Starts continuous conversion between the pins (pinP-pinN). More...

int	analogReadContinuous ()
	Reads the analog value of a continuous conversion. More...

void	stopContinuous ()
	Stops continuous conversion.

Frequency trigger methods
void	startTimer (uint32_t freq)
	Start the default timer (PDB) triggering the ADC at the frequency. More...

void	startPDB (uint32_t freq)
	Start PDB triggering the ADC at the frequency. More...

void	stopTimer ()
	Stop the default timer (PDB)

void	stopPDB ()
	Stop the PDB.

uint32_t	getTimerFrequency ()
	Return the default timer's (PDB) frequency. More...

uint32_t	getPDBFrequency ()
	Return the PDB's frequency. More...

Other methods and variables
struct ADC_Module::ADC_Config	adc_config

uint8_t	adcWasInUse
	Was the adc in use before a call?

uint8_t	num_measurements
	Number of measurements that the ADC is performing.

volatile ADC_ERROR	fail_flag
	This flag indicates that some kind of error took place. More...

const uint8_t	ADC_num
	Which adc is this?

void	saveConfig (ADC_Config *config)

void	loadConfig (const ADC_Config *config)

void	resetError ()
	Resets all errors from the ADC, if any.

Detailed Description

Implements all functions of the Teensy 3.x, LC, 4.x analog to digital converter.

Definition at line 54 of file ADC_Module.h.

Constructor & Destructor Documentation

◆ ADC_Module()

ADC_Module::ADC_Module	(	uint8_t	ADC_number,
		const uint8_t *const	a_channel2sc1a,
		const ADC_NLIST *const	a_diff_table,
		ADC_REGS_t &	a_adc_regs
	)

Pass the ADC number and the Channel number to SC1A number arrays.

Parameters

ADC_number	Number of the ADC module, from 0.
a_channel2sc1a	contains an index that pairs each pin to its SC1A number (used to start a conversion on that pin)
a_diff_table	is similar to a_channel2sc1a, but for differential pins.
a_adc_regs	pointer to start of the ADC registers

Definition at line 42 of file ADC_Module.cpp.

Member Function Documentation

◆ analogRead() [1/2]

int ADC_Module::analogRead ( ADC_INTERNAL_SOURCE pin )

inline

Returns the analog value of the special internal source, such as the temperature sensor.

Parameters

pin	ADC_INTERNAL_SOURCE to read.

Returns: the analog value of the pin.

Definition at line 459 of file ADC_Module.h.

◆ analogRead() [2/2]

int ADC_Module::analogRead ( uint8_t pin )

Returns the analog value of the pin.

It waits until the value is read and then returns the result. If a comparison has been set up and fails, it will return ADC_ERROR_VALUE. This function is interrupt safe, so it will restore the adc to the state it was before being called

Parameters

pin	pin to read.

Returns: the analog value of the pin.

Definition at line 1104 of file ADC_Module.cpp.

◆ analogReadContinuous()

int ADC_Module::analogReadContinuous ( )

inline

Reads the analog value of a continuous conversion.

If single-ended and 16 bits it's necessary to typecast it to an unsigned type (like uint16_t), otherwise values larger than 3.3/2 V are interpreted as negative!

Set the continuous conversion with with startContinuous(uint8_t pin) or startContinuousDifferential(uint8_t pinP, uint8_t pinN) (if exists).

Returns: the last converted value.

Definition at line 563 of file ADC_Module.h.

◆ analogReadDifferential()

int ADC_Module::analogReadDifferential	(	uint8_t	pinP,
		uint8_t	pinN
	)

Reads the differential analog value of two pins (pinP - pinN).

It waits until the value is read and then returns the result. If a comparison has been set up and fails, it will return ADC_ERROR_DIFF_VALUE.

This function is interrupt safe, so it will restore the adc to the state it was before being called

Parameters

pinP	must be A10 or A12.
pinN	must be A11 (if pinP=A10) or A13 (if pinP=A12).

Returns: the difference between the pins if they are valid, othewise returns ADC_ERROR_DIFF_VALUE.

Definition at line 1185 of file ADC_Module.cpp.

◆ checkDifferentialPins()

bool ADC_Module::checkDifferentialPins	(	uint8_t	pinP,
		uint8_t	pinN
	)

Check whether the pins are a valid analog differential pair of pins.

If PGA is enabled it also checks that this ADCx can use PGA on this pins

Parameters

pinP	positive pin to check.
pinN	negative pin to check.

Returns: true if the pin is valid, false otherwise.

Definition at line 991 of file ADC_Module.cpp.

◆ checkPin()

bool ADC_Module::checkPin ( uint8_t pin )

Check whether the pin is a valid analog pin.

Parameters

pin to check.

Returns: true if the pin is valid, false otherwise.

Definition at line 969 of file ADC_Module.cpp.

◆ enableCompare()

void ADC_Module::enableCompare	(	int16_t	compValue,
		bool	greaterThan
	)

Enable the compare function to a single value.

A conversion will be completed only when the ADC value is >= compValue (greaterThan=1) or < compValue (greaterThan=0)

Call it after changing the resolution. Use with interrupts or poll conversion completion with isComplete().

Parameters

compValue	value to compare
greaterThan	true or false

Definition at line 798 of file ADC_Module.cpp.

◆ enableCompareRange()

void ADC_Module::enableCompareRange	(	int16_t	lowerLimit,
		int16_t	upperLimit,
		bool	insideRange,
		bool	inclusive
	)

Enable the compare function to a range.

A conversion will be completed only when the ADC value is inside (insideRange=1) or outside (=0) the range given by (lowerLimit, upperLimit), including (inclusive=1) the limits or not (inclusive=0).

See Table 31-78, p. 617 of the freescale manual. Call it after changing the resolution. Use with interrupts or poll conversion completion with isComplete()

Parameters

lowerLimit	lower value to compare
upperLimit	upper value to compare
insideRange	true or false
inclusive	true or false

Definition at line 824 of file ADC_Module.cpp.

◆ enableDMA()

void ADC_Module::enableDMA ( )

Enable DMA request.

An ADC DMA request will be raised when the conversion is completed (including hardware averages and if the comparison (if any) is true).

Definition at line 764 of file ADC_Module.cpp.

◆ enableInterrupts()

void ADC_Module::enableInterrupts	(	void(*)(void)	isr,
		uint8_t	priority = `255`
	)

Enable interrupts.

An IRQ_ADCx interrupt will be raised when the conversion is completed (including hardware averages and if the comparison (if any) is true).

Parameters

isr	function (returns void and accepts no arguments) that will be executed after an interrupt.
priority	Interrupt priority, highest is 0, lowest is 255.

Definition at line 726 of file ADC_Module.cpp.

◆ enablePGA()

void ADC_Module::enablePGA ( uint8_t gain )

Enables the PGA and sets the gain.

Use only for signals lower than 1.2 V and only in differential mode

Parameters

gain	can be 1, 2, 4, 8, 16, 32 or 64

Definition at line 910 of file ADC_Module.cpp.

◆ getMaxValue()

uint32_t ADC_Module::getMaxValue ( )

Returns the maximum value for a measurement: 2^res-1.

Returns: the maximum value for a measurement: 2^res-1.

Definition at line 416 of file ADC_Module.cpp.

◆ getPDBFrequency()

uint32_t ADC_Module::getPDBFrequency ( )

Return the PDB's frequency.

Return the PDB's frequency

Returns: the timer's frequency in Hz.

Definition at line 1601 of file ADC_Module.cpp.

◆ getPGA()

uint8_t ADC_Module::getPGA ( )

Returns the PGA level.

Returns: PGA level from 1 to 64

Definition at line 952 of file ADC_Module.cpp.

◆ getResolution()

uint8_t ADC_Module::getResolution ( )

Returns the resolution of the ADC_Module.

Returns: the resolution of the ADC_Module.

Definition at line 408 of file ADC_Module.cpp.

◆ getTimerFrequency()

uint32_t ADC_Module::getTimerFrequency ( )

inline

Return the default timer's (PDB) frequency.

The default timer in this board is the PDB, you can also call it directly with getPDBFrequency().

Returns: the timer's frequency in Hz.

Definition at line 618 of file ADC_Module.h.

◆ isComplete()

volatile bool ADC_Module::isComplete ( )

inline

Is an ADC conversion ready?

When a value is read this function returns false until a new value exists, so it only makes sense to call it before analogReadContinuous() or readSingle()

Returns: true if yes, false if not.

Definition at line 340 of file ADC_Module.h.

◆ isContinuous()

volatile bool ADC_Module::isContinuous ( )

inline

Is the ADC in continuous mode?

Returns: true or false

Definition at line 362 of file ADC_Module.h.

◆ isConverting()

volatile bool ADC_Module::isConverting ( )

inline

Is the ADC converting at the moment?

Returns: true or false

Definition at line 323 of file ADC_Module.h.

◆ isDifferential()

volatile bool ADC_Module::isDifferential ( )

inline

Is the ADC in differential mode?

Returns: true or false

Definition at line 353 of file ADC_Module.h.

◆ isPGAEnabled()

volatile bool ADC_Module::isPGAEnabled ( )

inline

Is the PGA function enabled?

Returns: true or false

Definition at line 375 of file ADC_Module.h.

◆ loadConfig()

void ADC_Module::loadConfig ( const ADC_Config * config )

inline

Load config to the ADC

Parameters

config ADC_Config from where the config will be loaded

Definition at line 714 of file ADC_Module.h.

◆ readSingle()

int ADC_Module::readSingle ( )

inline

Reads the analog value of a single conversion. Set the conversion with with startSingleRead(uint8_t pin) or startSingleDifferential(uint8_t pinP, uint8_t pinN).

Returns: the converted value.

Definition at line 517 of file ADC_Module.h.

◆ recalibrate()

void ADC_Module::recalibrate ( )

Starts the calibration sequence, waits until it's done and writes the results.

Usually it's not necessary to call this function directly, but do it if the "environment" changed significantly since the program was started.

Definition at line 244 of file ADC_Module.cpp.

◆ saveConfig()

void ADC_Module::saveConfig ( ADC_Config * config )

inline

Save config of the ADC to the ADC_Config struct

Parameters

config ADC_Config where the config will be stored

Definition at line 696 of file ADC_Module.h.

◆ setAveraging()

void ADC_Module::setAveraging ( uint8_t num )

Set the number of averages.

Parameters

num	can be 0, 4, 8, 16 or 32.

It doesn't recalibrate at the end.

Definition at line 651 of file ADC_Module.cpp.

◆ setConversionSpeed()

void ADC_Module::setConversionSpeed ( ADC_CONVERSION_SPEED speed )

Sets the conversion speed (changes the ADC clock, ADCK)

Parameters

speed can be any from the ADC_CONVERSION_SPEED enum.

Definition at line 431 of file ADC_Module.cpp.

◆ setReference()

void ADC_Module::setReference ( ADC_REFERENCE ref_type )

Set the voltage reference you prefer, default is vcc.

Parameters

ref_type any of the ADC_REFERENCE enum.

It recalibrates at the end.

Definition at line 258 of file ADC_Module.cpp.

◆ setResolution()

void ADC_Module::setResolution ( uint8_t bits )

Change the resolution of the measurement.

Parameters

bits	is the number of bits of resolution. For single-ended measurements: 8, 10, 12 or 16 bits. For differential measurements: 9, 11, 13 or 16 bits. If you want something in between (11 bits single-ended for example) select the immediate higher and shift the result one to the right.

Whenever you change the resolution, change also the comparison values (if you use them).

Definition at line 312 of file ADC_Module.cpp.

◆ setSamplingSpeed()

void ADC_Module::setSamplingSpeed ( ADC_SAMPLING_SPEED speed )

Sets the sampling speed.

Increase the sampling speed for low impedance sources, decrease it for higher impedance ones.

Parameters

speed can be any of the ADC_SAMPLING_SPEED enum.

Definition at line 583 of file ADC_Module.cpp.

◆ startContinuous()

bool ADC_Module::startContinuous ( uint8_t pin )

Starts continuous conversion on the pin.

It returns as soon as the ADC is set, use analogReadContinuous() to read the value.

Parameters

pin	can be any of the analog pins

Returns: true if the pin is valid, false otherwise.

Definition at line 1365 of file ADC_Module.cpp.

◆ startContinuousDifferential()

bool ADC_Module::startContinuousDifferential	(	uint8_t	pinP,
		uint8_t	pinN
	)

Starts continuous conversion between the pins (pinP-pinN).

It returns as soon as the ADC is set, use analogReadContinuous() to read the value.

Parameters

pinP	must be A10 or A12.
pinN	must be A11 (if pinP=A10) or A13 (if pinP=A12).

Returns: true if the pins are valid, false otherwise.

Definition at line 1395 of file ADC_Module.cpp.

◆ startDifferentialFast()

void ADC_Module::startDifferentialFast	(	uint8_t	pinP,
		uint8_t	pinN
	)

Starts a differential conversion on the pair of pins.

It sets the mux correctly, doesn't do any of the checks on the pin and doesn't change the continuous conversion bit.

Parameters

pinP	positive pin to read.
pinN	negative pin to read.

Definition at line 1065 of file ADC_Module.cpp.

◆ startPDB()

void ADC_Module::startPDB ( uint32_t freq )

Start PDB triggering the ADC at the frequency.

Call startSingleRead or startSingleDifferential on the pin that you want to measure before calling this function. See the example adc_pdb.ino.

Parameters

freq	is the frequency of the ADC conversion, it can't be lower that 1 Hz

Definition at line 1460 of file ADC_Module.cpp.

◆ startReadFast()

void ADC_Module::startReadFast ( uint8_t pin )

Starts a single-ended conversion on the pin.

It sets the mux correctly, doesn't do any of the checks on the pin and doesn't change the continuous conversion bit.

Parameters

pin to read.

Definition at line 1032 of file ADC_Module.cpp.

◆ startSingleDifferential()

bool ADC_Module::startSingleDifferential	(	uint8_t	pinP,
		uint8_t	pinN
	)

Start a differential conversion between two pins (pinP - pinN) It returns immediately, get value with readSingle(). If this function interrupts a measurement, it stores the settings in adc_config.

Parameters

pinP	must be A10 or A12.
pinN	must be A11 (if pinP=A10) or A13 (if pinP=A12).

Returns: true if the pins are valid, false otherwise.

Definition at line 1316 of file ADC_Module.cpp.

◆ startSingleRead()

bool ADC_Module::startSingleRead ( uint8_t pin )

Starts an analog measurement on the pin. It returns immediately, get value with readSingle(). If this function interrupts a measurement, it stores the settings in adc_config.

Parameters

pin	pin to read.

Returns: true if the pin is valid, false otherwise.

Definition at line 1277 of file ADC_Module.cpp.

◆ startTimer()

void ADC_Module::startTimer ( uint32_t freq )

inline

Start the default timer (PDB) triggering the ADC at the frequency.

The default timer in this board is the PDB, you can also call it directly with startPDB(). Call startSingleRead or startSingleDifferential on the pin that you want to measure before calling this function. See the example adc_pdb.ino.

Parameters

freq	is the frequency of the ADC conversion, it can't be lower that 1 Hz

Definition at line 598 of file ADC_Module.h.

Member Data Documentation

◆ adc_config

struct ADC_Module::ADC_Config ADC_Module::adc_config

Struct with all relevant ADC configs.

◆ fail_flag

volatile ADC_ERROR ADC_Module::fail_flag

This flag indicates that some kind of error took place.

Use the defines at the beginning of this file to find out what caused the fail.

Definition at line 736 of file ADC_Module.h.

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

Classes

Public Member Functions

Other methods and variables

Detailed Description

Constructor & Destructor Documentation

◆ ADC_Module()

Member Function Documentation

◆ analogRead() [1/2]

◆ analogRead() [2/2]

◆ analogReadContinuous()

◆ analogReadDifferential()

◆ checkDifferentialPins()

◆ checkPin()

◆ enableCompare()

◆ enableCompareRange()

◆ enableDMA()

◆ enableInterrupts()

◆ enablePGA()

◆ getMaxValue()

◆ getPDBFrequency()

◆ getPGA()

◆ getResolution()

◆ getTimerFrequency()

◆ isComplete()

◆ isContinuous()

◆ isConverting()

◆ isDifferential()

◆ isPGAEnabled()

◆ loadConfig()

◆ readSingle()

◆ recalibrate()

◆ saveConfig()

◆ setAveraging()

◆ setConversionSpeed()

◆ setReference()

◆ setResolution()

◆ setSamplingSpeed()

◆ startContinuous()

◆ startContinuousDifferential()

◆ startDifferentialFast()

◆ startPDB()

◆ startReadFast()

◆ startSingleDifferential()

◆ startSingleRead()

◆ startTimer()

Member Data Documentation

◆ adc_config

◆ fail_flag