ADC: ADC_Module Class Reference

ADC 8.0 Analog to Digital Conversor library for the Teensy 3.6 microprocessor

Classes | Public Member Functions | Public Attributes | List of all members
ADC_Module Class Reference

`#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)
| Constructor. More...
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.
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 | 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.
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...
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...
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...
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...
bool | startSingleRead (uint8_t pin)
| Starts an analog measurement on the pin and enables interrupts. More...
bool | startSingleDifferential (uint8_t pinP, uint8_t pinN)
| Start a differential conversion between two pins (pinP - pinN) and enables interrupts. More...
int | readSingle ()
| Reads the analog value of a single conversion. More...
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.
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...
void | saveConfig (ADC_Config *config)
void | loadConfig (const ADC_Config *config)
void | resetError ()
| Resets all errors from the ADC, if any.

## Public Attributes
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?

## Detailed Description

Class ADC_Module: Implements all functions of the Teensy 3.x, LC analog to digital converter

## 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
| ) |  |

Constructor.

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

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

It calls analogRead(uint8_t pin) internally, with the correct value for the pin for all boards. Possible values: TEMP_SENSOR, Temperature sensor. VREF_OUT, 1.2 V reference (switch on first using VREF.h). BANDGAP, BANDGAP (switch on first using VREF.h). VREFH, High VREF. VREFL, Low VREF.

Parameters

  pin | ADC_INTERNAL_SOURCE to read.

Returns
  the value of the pin.

## ◆ 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 value of the pin.

## ◆ analogReadContinuous()

int ADC_Module::analogReadContinuous | ( |  | ) |
| inline

Reads the analog value of a continuous conversion.

Set the continuous conversion with with analogStartContinuous(pin) or startContinuousDifferential(pinP, pinN).

Returns
  the last converted value. 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!

## ◆ 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.

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. This function is interrupt safe, so it will restore the adc to the state it was before being called

## ◆ 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.

## ◆ 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.

## ◆ 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

## ◆ 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

## ◆ 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).

## ◆ 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.

## ◆ 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.

## ◆ getPDBFrequency()

uint32_t ADC_Module::getPDBFrequency | ( |  | ) |

Return the PDB's frequency.

Return the PDB's frequency

Returns
  the timer's frequency in Hz.

## ◆ getResolution()

uint8_t ADC_Module::getResolution | ( |  | ) |

Returns the resolution of the ADC_Module.

Returns
  the resolution of the ADC_Module.

## ◆ 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.

## ◆ isComplete()

volatile bool ADC_Module::isComplete | ( |  | ) |
| inline

Is an ADC conversion ready?

Returns
  true if yes, false if not. 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()

## ◆ isContinuous()

volatile bool ADC_Module::isContinuous | ( |  | ) |
| inline

Is the ADC in continuous mode?

Returns
  true or false

## ◆ isConverting()

volatile bool ADC_Module::isConverting | ( |  | ) |
| inline

Is the ADC converting at the moment?

Returns
  true or false

## ◆ isDifferential()

volatile bool ADC_Module::isDifferential | ( |  | ) |
| inline

Is the ADC in differential mode?

Returns
  true or false

## ◆ 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

## ◆ readSingle()

int ADC_Module::readSingle | ( |  | ) |
| inline

Reads the analog value of a single conversion.

Set the conversion with with startSingleRead(pin) or startSingleDifferential(pinP, pinN).

Returns
  the converted value.

## ◆ 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.

## ◆ 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

## ◆ 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.

## ◆ 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: VERY_LOW_SPEED, LOW_SPEED, MED_SPEED, HIGH_SPEED_16BITS, HIGH_SPEED, VERY_HIGH_SPEED, ADACK_2_4, ADACK_4_0, ADACK_5_2 or ADACK_6_2.

VERY_LOW_SPEED is guaranteed to be the lowest possible speed within specs for resolutions less than 16 bits (higher than 1 MHz), it's different from LOW_SPEED only for 24, 4 or 2 MHz bus frequency. LOW_SPEED is guaranteed to be the lowest possible speed within specs for all resolutions (higher than 2 MHz). MED_SPEED is always >= LOW_SPEED and <= HIGH_SPEED. HIGH_SPEED_16BITS is guaranteed to be the highest possible speed within specs for all resolutions (lower or eq than 12 MHz). HIGH_SPEED is guaranteed to be the highest possible speed within specs for resolutions less than 16 bits (lower or eq than 18 MHz). VERY_HIGH_SPEED may be out of specs, it's different from HIGH_SPEED only for 48, 40 or 24 MHz bus frequency.

Additionally the conversion speed can also be ADACK_2_4, ADACK_4_0, ADACK_5_2 and ADACK_6_2, where the numbers are the frequency of the ADC clock (ADCK) in MHz and are independent on the bus speed. This is useful if you are using the Teensy at a very low clock frequency but want faster conversions, but if F_BUS<F_ADCK, you can't use VERY_HIGH_SPEED for sampling speed.

## ◆ setReference()

void ADC_Module::setReference | ( | ADC_REFERENCE | ref_type | ) |

Set the voltage reference you prefer, default is vcc.

Parameters

  ref_type | can be ADC_REFERENCE::REF_3V3, ADC_REFERENCE::REF_1V2 (not for Teensy LC) or ADC_REFERENCE::REF_EXT

It recalibrates at the end.

## ◆ 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).

## ◆ 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: VERY_LOW_SPEED, LOW_SPEED, MED_SPEED, HIGH_SPEED or VERY_HIGH_SPEED.

VERY_LOW_SPEED is the lowest possible sampling speed (+24 ADCK). LOW_SPEED adds +16 ADCK. MED_SPEED adds +10 ADCK. HIGH_SPEED adds +6 ADCK. VERY_HIGH_SPEED is the highest possible sampling speed (0 ADCK added).

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ 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

## ◆ 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.

## ◆ startSingleDifferential()

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

Start a differential conversion between two pins (pinP - pinN) and enables interrupts.

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.

## ◆ startSingleRead()

bool ADC_Module::startSingleRead | ( | uint8_t | pin | ) |

Starts an analog measurement on the pin and enables interrupts.

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.

## ◆ 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

## Member Data Documentation

## ◆ 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.

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

- ADC_Module.h