This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Analog-to-Digital Converter functionality, for the conversion of analog voltages into a corresponding digital form.
The following driver Application Programming Interface (API) modes are covered by this manual:
The following peripheral is used by this module:
The following devices can use this module:
The outline of this documentation is as follows:
There are no prerequisites for this module.
This driver provides an interface for the Analog-to-Digital conversion functions on the device, to convert analog voltages to a corresponding digital value. The ADC has up to 12-bit resolution, and is capable of converting up to 500K samples per second (KSPS).
The ADC has a compare function for accurate monitoring of user defined thresholds with minimum software intervention required. The ADC may be configured for 8-, 10-, or 12-bit result, reducing the conversion time. ADC conversion results are provided left or right adjusted which eases calculation when the result is represented as a signed integer.
The input selection is flexible, and both single-ended and differential measurements can be made. For differential measurements, an optional gain stage is available to increase the dynamic range. In addition, several internal signal inputs are available. The ADC can provide both signed and unsigned results.
The ADC measurements can either be started by application software or an incoming event from another peripheral in the device, and both internal and external reference voltages can be selected.
A simplified block diagram of the ADC can be seen in the figure below.
The ADC features a prescaler, which enables conversion at lower clock rates than the input Generic Clock to the ADC module. This feature can be used to lower the synchronization time of the digital interface to the ADC module via a high speed Generic Clock frequency, while still allowing the ADC sampling rate to be reduced.
The ADC supports full 8-, 10-, or 12-bit resolution. Hardware oversampling and decimation can be used to increase the effective resolution at the expense of throughput. Using oversampling and decimation mode the ADC resolution is increased from 12-bit to an effective 13-, 14-, 15-, or 16-bit. In these modes the conversion rate is reduced, as a greater number of samples is used to achieve the increased resolution. The available resolutions and effective conversion rate is listed in the table below.
| Resolution | Effective conversion rate |
|---|---|
| 13-bit | Conversion rate divided by 4 |
| 14-bit | Conversion rate divided by 16 |
| 15-bit | Conversion rate divided by 64 |
| 16-bit | Conversion rate divided by 256 |
ADC conversions can be software triggered on demand by the user application, if continuous sampling is not required. It is also possible to configure the ADC in free running mode, where new conversions are started as soon as the previous conversion is completed, or configure the ADC to scan across a number of input pins (see Pin Scan).
The ADC has two conversion modes; differential and single-ended. When measuring signals where the positive input pin is always at a higher voltage than the negative input pin, the single-ended conversion mode should be used in order to achieve a full 12-bit output resolution.
If however the positive input pin voltage may drop below the negative input pin the signed differential mode should be used.
The sample time for each ADC conversion is configurable as a number of half prescaled ADC clock cycles (depending on the prescaler value), allowing the user application to achieve faster or slower sampling depending on the source impedance of the ADC input channels. For applications with high impedance inputs the sample time can be increased to give the ADC an adequate time to sample and convert the input channel.
The resulting sampling time is given by the following equation:
\[ t_{SAMPLE} = (sample\_length+1) \times \frac{ADC_{CLK}} {2} \]
The ADC can be configured to trade conversion speed for accuracy by averaging multiple samples in hardware. This feature is suitable when operating in noisy conditions.
You can specify any number of samples to accumulate (up to 1024) and the divide ratio to use (up to divide by 128). To modify these settings the ADC_RESOLUTION_CUSTOM needs to be set as the resolution. When this is set the number of samples to accumulate and the division ratio can be set by the configuration struct members adc_config.accumulate_samples and adc_config.divide_result. When using this mode the ADC result register will be set to be 16-bit wide to accommodate the larger result sizes produced by the accumulator.
The effective ADC conversion rate will be reduced by a factor of the number of accumulated samples; however, the effective resolution will be increased according to the table below.
| Number of samples | Final result |
|---|---|
| 1 | 12-bit |
| 2 | 13-bit |
| 4 | 14-bit |
| 8 | 15-bit |
| 16 | 16-bit |
| 32 | 16-bit |
| 64 | 16-bit |
| 128 | 16-bit |
| 256 | 16-bit |
| 512 | 16-bit |
| 1024 | 16-bit |
Inherent gain and offset errors affect the absolute accuracy of the ADC.
The offset error is defined as the deviation of the ADC's actual transfer function from ideal straight line at zero input voltage.
The gain error is defined as the deviation of the last output step's midpoint from the ideal straight line, after compensating for offset error.
The offset correction value is subtracted from the converted data before the result is ready. The gain correction value is multiplied with the offset corrected value.
The equation for both offset and gain error compensation is shown below:
\[ ADC_{RESULT} = (VALUE_{CONV} + CORR_{OFFSET}) \times CORR_{GAIN} \]
When enabled, a given set of offset and gain correction values can be applied to the sampled data in hardware, giving a corrected stream of sample data to the user application at the cost of an increased sample latency.
In single conversion, a latency of 13 ADC Generic Clock cycles is added for the final sample result availability. As the correction time is always less than the propagation delay, in free running mode this latency appears only during the first conversion. After the first conversion is complete, future conversion results are available at the defined sampling rate.
In pin scan mode, the first ADC conversion will begin from the configured positive channel, plus the requested starting offset. When the first conversion is completed, the next conversion will start at the next positive input channel and so on, until all requested pins to scan have been sampled and converted. SAM L21/L22 has automatic sequences feature instead of pin scan mode. In automatic sequence mode, all of 32 positives inputs can be included in a sequence. The sequence starts from the lowest input, and go to the next enabled input automatically.
Pin scanning gives a simple mechanism to sample a large number of physical input channel samples, using a single physical ADC channel.
The ADC module window monitor function can be used to automatically compare the conversion result against a preconfigured pair of upper and lower threshold values.
The threshold values are evaluated differently, depending on whether differential or single-ended mode is selected. In differential mode, the upper and lower thresholds are evaluated as signed values for the comparison, while in single-ended mode the comparisons are made as a set of unsigned values.
The significant bits of the lower window monitor threshold and upper window monitor threshold values are user-configurable, and follow the overall ADC sampling bit precision set when the ADC is configured by the user application. For example, only the eight lower bits of the window threshold values will be compared to the sampled data whilst the ADC is configured in 8-bit mode. In addition, if using differential mode, the 8th bit will be considered as the sign bit even if bit 9 is zero.
Event generation and event actions are configurable in the ADC.
The ADC has two actions that can be triggered upon event reception:
The ADC can generate two events:
If the event actions are enabled in the configuration, any incoming event will trigger the action.
If the window monitor event is enabled, an event will be generated when the configured window condition is detected.
If the result ready event is enabled, an event will be generated when a conversion is completed.
An integrated analog temperature sensor is available for use with the ADC. The bandgap voltage, as well as the scaled I/O and core voltages can also be measured by the ADC. For internal ADC inputs, the internal source(s) may need to be manually enabled by the user application before they can be measured.
For extra information, see Extra Information for ADC Driver. This includes:
For a list of examples related to this driver, see Examples for ADC Driver.
Modules | |
| Related Project(s) | |
| In this section you can find all the projects related to the SAM Analog-to-Digital Converter (ADC) Driver. | |
Enumerations | |
| enum | adc_job_type { ADC_JOB_READ_BUFFER } |
| Enum for the possible types of ADC asynchronous jobs that may be issued to the driver. More... | |
Callback Management | |
| void | adc_register_callback (struct adc_module *const module, adc_callback_t callback_func, enum adc_callback callback_type) |
| void | adc_unregister_callback (struct adc_module *module, enum adc_callback callback_type) |
| static void | adc_enable_callback (struct adc_module *const module, enum adc_callback callback_type) |
| Enables callback. More... | |
| static void | adc_disable_callback (struct adc_module *const module, enum adc_callback callback_type) |
| Disables callback. More... | |
Job Management | |
| enum status_code | adc_read_buffer_job (struct adc_module *const module_inst, uint16_t *buffer, uint16_t samples) |
| enum status_code | adc_get_job_status (struct adc_module *module_inst, enum adc_job_type type) |
| void | adc_abort_job (struct adc_module *module_inst, enum adc_job_type type) |
Module Status Flags | |
ADC status flags, returned by adc_get_status() and cleared by adc_clear_status(). | |
| #define | ADC_STATUS_RESULT_READY (1UL << 0) |
| ADC result ready. More... | |
| #define | ADC_STATUS_WINDOW (1UL << 1) |
| Window monitor match. More... | |
| #define | ADC_STATUS_OVERRUN (1UL << 2) |
| ADC result overwritten before read. More... | |
Driver Initialization and Configuration | |
| enum status_code | adc_init (struct adc_module *const module_inst, Adc *hw, struct adc_config *config) |
| void | adc_get_config_defaults (struct adc_config *const config) |
Status Management | |
| static uint32_t | adc_get_status (struct adc_module *const module_inst) |
| Retrieves the current module status. More... | |
| static void | adc_clear_status (struct adc_module *const module_inst, const uint32_t status_flags) |
| Clears a module status flag. More... | |
Enable, Disable, and Reset ADC Module, Start Conversion and Read Result | |
| static enum status_code | adc_enable (struct adc_module *const module_inst) |
| Enables the ADC module. More... | |
| static enum status_code | adc_disable (struct adc_module *const module_inst) |
| Disables the ADC module. More... | |
| static enum status_code | adc_reset (struct adc_module *const module_inst) |
| Resets the ADC module. More... | |
| static void | adc_enable_events (struct adc_module *const module_inst, struct adc_events *const events) |
| Enables an ADC event input or output. More... | |
| static void | adc_disable_events (struct adc_module *const module_inst, struct adc_events *const events) |
| Disables an ADC event input or output. More... | |
| static void | adc_start_conversion (struct adc_module *const module_inst) |
| Starts an ADC conversion. More... | |
| static enum status_code | adc_read (struct adc_module *const module_inst, uint16_t *result) |
| Reads the ADC result. More... | |
Runtime Changes of ADC Module | |
| static void | adc_flush (struct adc_module *const module_inst) |
| Flushes the ADC pipeline. More... | |
| void | adc_set_window_mode (struct adc_module *const module_inst, const enum adc_window_mode window_mode, const int16_t window_lower_value, const int16_t window_upper_value) |
| static void | adc_set_positive_input (struct adc_module *const module_inst, const enum adc_positive_input positive_input) |
| Sets positive ADC input pin. More... | |
| static void | adc_set_negative_input (struct adc_module *const module_inst, const enum adc_negative_input negative_input) |
| Sets negative ADC input pin for differential mode. More... | |
Enable and Disable Interrupts | |
| static void | adc_enable_interrupt (struct adc_module *const module_inst, enum adc_interrupt_flag interrupt) |
| Enable interrupt. More... | |
| static void | adc_disable_interrupt (struct adc_module *const module_inst, enum adc_interrupt_flag interrupt) |
| Disable interrupt. More... | |
| #define ADC_STATUS_OVERRUN (1UL << 2) |
ADC result overwritten before read.
Referenced by adc_clear_status(), adc_get_status(), and adc_read().
| #define ADC_STATUS_RESULT_READY (1UL << 0) |
ADC result ready.
Referenced by adc_clear_status(), adc_get_status(), adc_read(), adc_start_read_result(), and adc_window_monitor().
| #define ADC_STATUS_WINDOW (1UL << 1) |
Window monitor match.
Referenced by adc_clear_status(), adc_get_status(), and adc_window_monitor().
| enum adc_job_type |
| void adc_abort_job | ( | struct adc_module * | module_inst, |
| enum adc_job_type | type | ||
| ) |
|
inlinestatic |
Clears a module status flag.
Clears the given status flag of the module.
| [in] | module_inst | Pointer to the ADC software instance struct |
| [in] | status_flags | Bitmask of ADC_STATUS_* flags to clear |
References ADC_STATUS_OVERRUN, ADC_STATUS_RESULT_READY, ADC_STATUS_WINDOW, and Assert.
Referenced by adc_read().
|
inlinestatic |
Disables the ADC module.
Disables an ADC module that was previously enabled.
| [in] | module_inst | Pointer to the ADC software instance struct |
References Assert, STATUS_OK, system_interrupt_disable(), and SYSTEM_INTERRUPT_MODULE_ADC.
Referenced by adc_differential(), adc_hardware_averaging(), adc_oversampling(), adc_reset(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().
|
inlinestatic |
Disables callback.
Disables the callback function registered by the adc_register_callback.
| [in] | module | Pointer to ADC software instance struct |
| [in] | callback_type | Callback type given by an enum |
| STATUS_OK | If operation was completed |
| STATUS_ERR_INVALID | If operation was not completed, due to invalid callback_type |
References adc_disable_interrupt(), and Assert.
Referenced by cleanup_adc_callback_mode_test(), and cleanup_adc_window_mode_test().
|
inlinestatic |
Disables an ADC event input or output.
Disables one or more input or output events to or from the ADC module. See Struct adc_events for a list of events this module supports.
| [in] | module_inst | Software instance for the ADC peripheral |
| [in] | events | Struct containing flags of events to disable |
References Assert.
|
inlinestatic |
Disable interrupt.
Disable the given interrupt request from the ADC module.
| [in] | module_inst | Pointer to the ADC software instance struct |
| [in] | interrupt | Interrupt to disable |
References Assert.
Referenced by adc_disable_callback().
|
inlinestatic |
Enables the ADC module.
Enables an ADC module that has previously been configured. If any internal reference is selected it will be enabled.
| [in] | module_inst | Pointer to the ADC software instance struct |
References Assert, STATUS_OK, system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_ADC.
Referenced by _lightsensor_init(), adc_correction_start(), adc_correction_stop(), adc_setup(), adp_example_adc_init(), configure_adc(), configure_adc_averaging(), configure_adc_differential(), configure_adc_sampling(), configure_adc_temp(), configure_adc_window_monitor(), configure_light_sensor(), run_adc_init_test(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().
|
inlinestatic |
Enables callback.
Enables the callback function registered by adc_register_callback. The callback function will be called from the interrupt handler when the conditions for the callback type are met.
| [in] | module | Pointer to ADC software instance struct |
| [in] | callback_type | Callback type given by an enum |
| STATUS_OK | If operation was completed |
| STATUS_ERR_INVALID | If operation was not completed, due to invalid callback_type |
References adc_enable_interrupt(), and Assert.
Referenced by adc_setup(), configure_adc_callbacks(), setup_adc_callback_mode_test(), and setup_adc_window_mode_test().
|
inlinestatic |
Enables an ADC event input or output.
Enables one or more input or output events to or from the ADC module. See Struct adc_events for a list of events this module supports.
| [in] | module_inst | Software instance for the ADC peripheral |
| [in] | events | Struct containing flags of events to enable |
References Assert.
|
inlinestatic |
Enable interrupt.
Enable the given interrupt request from the ADC module.
| [in] | module_inst | Pointer to the ADC software instance struct |
| [in] | interrupt | Interrupt to enable |
References Assert.
Referenced by adc_enable_callback().
|
inlinestatic |
Flushes the ADC pipeline.
Flushes the pipeline and restarts the ADC clock on the next peripheral clock edge. All conversions in progress will be lost. When flush is complete, the module will resume where it left off.
| [in] | module_inst | Pointer to the ADC software instance struct |
References Assert.
Referenced by run_adc_polled_mode_test().
| void adc_get_config_defaults | ( | struct adc_config *const | config | ) |
Referenced by _lightsensor_init(), adc_correction_start(), adc_correction_stop(), adc_setup(), adp_example_adc_init(), configure_adc(), configure_adc_averaging(), configure_adc_differential(), configure_adc_sampling(), configure_adc_temp(), configure_adc_window_monitor(), configure_light_sensor(), run_adc_init_test(), sam0_sensors_init(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().
| enum status_code adc_get_job_status | ( | struct adc_module * | module_inst, |
| enum adc_job_type | type | ||
| ) |
|
inlinestatic |
Retrieves the current module status.
Retrieves the status of the module, giving overall state information.
| [in] | module_inst | Pointer to the ADC software instance struct |
ADC_STATUS_* flags.| ADC_STATUS_RESULT_READY | ADC result is ready to be read |
| ADC_STATUS_WINDOW | ADC has detected a value inside the set window range |
| ADC_STATUS_OVERRUN | ADC result has overrun |
References ADC_STATUS_OVERRUN, ADC_STATUS_RESULT_READY, ADC_STATUS_WINDOW, and Assert.
Referenced by adc_read(), adc_start_read_result(), and adc_window_monitor().
| enum status_code adc_init | ( | struct adc_module *const | module_inst, |
| Adc * | hw, | ||
| struct adc_config * | config | ||
| ) |
Referenced by _lightsensor_init(), adc_correction_start(), adc_correction_stop(), adc_setup(), adp_example_adc_init(), configure_adc(), configure_adc_averaging(), configure_adc_differential(), configure_adc_sampling(), configure_adc_temp(), configure_adc_window_monitor(), configure_light_sensor(), run_adc_init_test(), sam0_sensors_init(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().
|
inlinestatic |
Reads the ADC result.
Reads the result from an ADC conversion that was previously started.
| [in] | module_inst | Pointer to the ADC software instance struct |
| [out] | result | Pointer to store the result value in |
| STATUS_OK | The result was retrieved successfully |
| STATUS_BUSY | A conversion result was not ready |
| STATUS_ERR_OVERFLOW | The result register has been overwritten by the ADC module before the result was read by the software |
References adc_clear_status(), adc_get_status(), ADC_STATUS_OVERRUN, ADC_STATUS_RESULT_READY, Assert, STATUS_BUSY, STATUS_ERR_OVERFLOW, and STATUS_OK.
Referenced by adc_start_read_result(), adc_window_monitor(), adp_example_adc_get_value(), io1_board_get_lightvalue(), main(), run_adc_average_mode_test(), and run_adc_polled_mode_test().
| enum status_code adc_read_buffer_job | ( | struct adc_module *const | module_inst, |
| uint16_t * | buffer, | ||
| uint16_t | samples | ||
| ) |
Referenced by main(), and run_adc_callback_mode_test().
| void adc_register_callback | ( | struct adc_module *const | module, |
| adc_callback_t | callback_func, | ||
| enum adc_callback | callback_type | ||
| ) |
Referenced by adc_setup(), configure_adc_callbacks(), setup_adc_callback_mode_test(), and setup_adc_window_mode_test().
|
inlinestatic |
Resets the ADC module.
Resets an ADC module, clearing all module state, and registers to their default values.
| [in] | module_inst | Pointer to the ADC software instance struct |
References adc_disable(), Assert, and STATUS_OK.
|
inlinestatic |
Sets negative ADC input pin for differential mode.
Sets the negative ADC input pin, when the ADC is configured in differential mode.
| [in] | module_inst | Pointer to the ADC software instance struct |
| [in] | negative_input | Negative input pin |
References Assert.
|
inlinestatic |
Sets positive ADC input pin.
Sets the positive ADC input pin selection.
| [in] | module_inst | Pointer to the ADC software instance struct |
| [in] | positive_input | Positive input pin |
References Assert.
| void adc_set_window_mode | ( | struct adc_module *const | module_inst, |
| const enum adc_window_mode | window_mode, | ||
| const int16_t | window_lower_value, | ||
| const int16_t | window_upper_value | ||
| ) |
|
inlinestatic |
Starts an ADC conversion.
Starts a new ADC conversion.
| [in] | module_inst | Pointer to the ADC software instance struct |
References Assert.
Referenced by adc_start_read_result(), adc_window_monitor(), adp_example_adc_get_value(), io1_board_prepare_to_get_info(), main(), run_adc_average_mode_test(), run_adc_polled_mode_test(), and setup_adc_window_mode_test().
| void adc_unregister_callback | ( | struct adc_module * | module, |
| enum adc_callback | callback_type | ||
| ) |
Referenced by cleanup_adc_callback_mode_test(), and cleanup_adc_window_mode_test().
1.8.5