Overview

This module contains functions that access analog to digital converter (ADC) peripherals.

When utilizing this module, acquiring ADC data is a two step process: requesting sample conversions (using adc.sample) and extraction of conversion results from a conversion buffer (using adc.getsample, adc.getsamples or adc.insertsamples). Various configuration parameters are available to set conversion rate, how results are extracted from the buffer and how these results are processed prior to extraction.

This module can be utilized if the device in use has a supported ADC peripheral (see status for details) and if ADC functionality is enabled at build time (see building).

Functions

adc.sample( id, count )

Initiate conversion and buffering of samples on an ADC channel.

Arguments:

  • id - ADC channel ID. Optionally, this may be a table containing a list of channel IDs (i.e.: {0, 2, 3}), allowing synchronization of acquisition. NOTE: This acceptance of mixed types is only for the sample function.
  • count - number of samples to acquire and place in buffer.

Returns: nothing.

sample = adc.getsample( id )

Get a single conversion value from the buffer associated with a given channel.

Arguments: id - ADC channel ID.

Returns: sample - numeric value of conversion, or nil if sample was not available.

samples = adc.getsamples( id, count )

Get multiple conversion values from the buffer associated with a given channel.

Arguments:

  • id - ADC channel ID.
  • count - optional parameter to indicate number of samples to return. If not included, all available samples are returned.

Returns: samples - table containing integer conversion values. If not enough samples are available, remaining indices will be nil.

adc.insertsamples( id, table, idx, count )

Get multiple conversion values from a channel's buffer, and write them into a table.

Arguments:

  • id - ADC channel ID.
  • table - table to write samples to. Values at table[idx] to table[idx + count -1] will be overwritten with samples (or nil if not enough samples are available).
  • idx - first index to use in the table for writing samples.
  • count - number of samples to return. If not enough samples are available (after blocking, if enabled) remaining values will be nil.

Returns: nothing.

maxval = adc.maxval( id )

Get the maximum value (corresponding to the maximum voltage) that can be returned on a given channel.

Arguments: id - ADC channel ID.

Returns: maxval - maximum integer conversion value (based on channel resolution)

clock = adc.setclock( id, clock, timer_id )

Set the frequency (number of samples per second) at which voltages will be converted into samples.

Arguments:

  • id - ADC channel ID.
  • clock - frequency to acquire samples at in Hz (number of samples per second), 0 to acquire as fast as possible.
  • timer_id - Timer channel ID to use to control ADC conversion. Note: At this time, a timer selection will apply to all channels on a given ADC peripheral.

Returns: clock - actual acquisition frequency to be used

status = adc.isdone( id )

Check whether samples are still being acquired on a channel.

Arguments: id - ADC channel ID.

Returns: status - 1 if no samples are being acquired, 0 if samples are pending acquisition.

adc.setblocking( id, mode )

Set whether or not functions that request converted samples should wait for requested samples or return immediately with what is available.

Arguments:

  • id - ADC channel ID.
  • mode - 1 if requests to get samples should block until requested samples are available or sampling has completed, 0 to return immediately with available samples

Returns: nothing.

adc.setsmoothing( id, length )

Set the length of the moving average filter. When length is greater than 1, samples pulled from the conversion buffer will be averaged with the preceding length - 1 buffered values.

Arguments:

  • id - ADC channel ID.
  • length - number of preceding samples to include in moving average filter (must be a power of 2). If 1, filter is disabled. When enabled, a filter buffer is filled before the main conversion buffer, so that averages are always over the same number of samples.

Returns: nothing.