Loading...
Searching...
No Matches

Low-level ADC peripheral driver interface. More...

Detailed Description

Low-level ADC peripheral driver interface.

This is a very simple ADC interface to allow platform independent access to a MCU's ADC unit(s). This interface is intentionally designed as simple as possible, to allow for very easy implementation and maximal portability.

As of now, the interface does not allow for any advanced ADC concepts (e.g. continuous mode, scan sequences, injections). It is to be determined, if these features will ever be integrated in this interface, or if it does make more sense to create a second, advanced ADC interface for this.

The ADC driver interface is built around the concept of ADC lines. An ADC line in this context is a tuple consisting out of a hardware ADC device (an ADC functional unit on the MCU) and an ADC channel connected to pin.

If a MCU has more than one hardware ADC unit, the ADC lines can be mapped in a way, that it is possible to sample multiple lines in parallel, given that the ADC implementation allows for interruption of the program flow while waiting for the result of a conversion (e.g. through putting the calling thread to sleep while waiting for the conversion results).

(Low-) Power Implications

The ADC peripheral(s) should only be powered on while adc_sample() is active. For implementing adc_sample() this means, that the peripheral should be powered on (i.e. through peripheral clock gating) at the beginning of the function and it should be powered back off at the end of the function.

If the adc_sample() function is implemented in a way, that it will put the active thread to sleep for a certain amount of time, the implementation might need to block certain power states.

Todo:
Extend interface for continuous mode?

Files

file  adc.h
 Low-level ADC peripheral driver interface definitions.
 

Macros

#define ADC_UNDEF   (UINT_FAST8_MAX)
 Default ADC undefined value.
 
#define ADC_LINE(x)   (x)
 Default ADC line access macro.
 

Typedefs

typedef uint_fast8_t adc_t
 Define default ADC type identifier.
 

Enumerations

enum  adc_res_t {
  ADC_RES_6BIT = 0 , ADC_RES_8BIT , ADC_RES_10BIT , ADC_RES_12BIT ,
  ADC_RES_14BIT , ADC_RES_16BIT
}
 Possible ADC resolution settings. More...
 

Functions

int adc_init (adc_t line)
 Initialize the given ADC line.
 
int32_t adc_sample (adc_t line, adc_res_t res)
 Sample a value from the given ADC line.
 
void adc_continuous_begin (adc_res_t res)
 Configure the ADC with a given resolution for continuous sampling.
 
int32_t adc_continuous_sample (adc_t line)
 Sample an ADC line without powering off the ADC afterward.
 
void adc_continuous_stop (void)
 Disable the ADC to save power.
 

Macro Definition Documentation

◆ ADC_LINE

#define ADC_LINE (   x)    (x)

Default ADC line access macro.

Definition at line 86 of file adc.h.

◆ ADC_UNDEF

#define ADC_UNDEF   (UINT_FAST8_MAX)

Default ADC undefined value.

Definition at line 79 of file adc.h.

Typedef Documentation

◆ adc_t

typedef uint_fast8_t adc_t

Define default ADC type identifier.

Definition at line 72 of file adc.h.

Enumeration Type Documentation

◆ adc_res_t

enum adc_res_t

Possible ADC resolution settings.

Enumerator
ADC_RES_6BIT 

ADC resolution: 6 bit.

ADC_RES_8BIT 

ADC resolution: 8 bit.

ADC_RES_10BIT 

ADC resolution: 10 bit.

ADC_RES_12BIT 

ADC resolution: 12 bit.

ADC_RES_14BIT 

ADC resolution: 14 bit.

ADC_RES_16BIT 

ADC resolution: 16 bit.

Definition at line 93 of file adc.h.

Function Documentation

◆ adc_continuous_begin()

void adc_continuous_begin ( adc_res_t  res)

Configure the ADC with a given resolution for continuous sampling.

Note
requires the periph_adc_continuous feature
Parameters
[in]resresolution to use for conversion

◆ adc_continuous_sample()

int32_t adc_continuous_sample ( adc_t  line)

Sample an ADC line without powering off the ADC afterward.

Note
requires the periph_adc_continuous feature

Sample a value from the given ADC line

Returns
the sampled value on success

◆ adc_continuous_stop()

void adc_continuous_stop ( void  )

Disable the ADC to save power.

Note
requires the periph_adc_continuous feature

◆ adc_init()

int adc_init ( adc_t  line)

Initialize the given ADC line.

The ADC line is initialized in synchronous, blocking mode.

Parameters
[in]lineline to initialize
Returns
0 on success
-1 on invalid ADC line

◆ adc_sample()

int32_t adc_sample ( adc_t  line,
adc_res_t  res 
)

Sample a value from the given ADC line.

This function blocks until the conversion has finished. Please note, that if more than one line share the same ADC device, and if these lines are sampled at the same time (e.g. from different threads), the one called secondly waits for the first to finish before its conversion starts.

Parameters
[in]lineline to sample
[in]resresolution to use for conversion
Returns
the sampled value on success
-1 if resolution is not applicable