| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Typedefs | Functions
ADC Peripheral Driver
Analog-to-Digital Converter (ADC)

The section describes the programming interface of the ADC Peripheral driver. More...

## Data Structures
struct | adc_calibration_param_t
| Defines the calibration parameter structure. More...
struct | adc_user_config_t
| Defines the ADC basic configuration structure. More...
struct | adc_extend_config_t
| Defines the ADC extended configuration structure. More...
struct | adc_channel_config_t
| Defines the channel configuration structure. More...

## Typedefs
typedef void(* | adc_isr_callback_t )(void)
| Defines the ADC ISR callback function. More...

## Functions
adc_status_t | adc_get_calibration_param (uint32_t instance, adc_calibration_param_t *paramPtr)
| Gets the parameters for calibration. More...
adc_status_t | adc_set_calibration_param (uint32_t instance, adc_calibration_param_t *paramPtr)
| Sets the parameters for calibration. More...
adc_status_t | adc_auto_calibration (uint32_t instance, adc_calibration_param_t *paramPtr)
| Executes the auto calibration. More...
adc_status_t | adc_init (uint32_t instance, adc_user_config_t *cfgPtr)
| Initializes the ADC with the basic configuration. More...
adc_status_t | adc_init_extend (uint32_t instance, adc_extend_config_t *extendCfgPtr)
| Initializes the ADC with the extended configurations when necessary. More...
void | adc_shutdown (uint32_t instance)
| Shuts down the ADC. More...
adc_status_t | adc_start_conversion (uint32_t instance, adc_channel_config_t *channelCfgPtr)
| Starts the conversion from the indicated channel. More...
adc_status_t | adc_stop_conversion (uint32_t instance, adc_channel_config_t *channelCfgPtr)
| Stops the conversion. More...
bool | adc_is_conversion_completed (uint32_t instance, adc_channel_config_t *channelCfgPtr)
| Checks whether the conversion is completed. More...
uint32_t | adc_get_conversion_value (uint32_t instance, adc_channel_config_t *channelCfgPtr)
| Gets the value after the conversion. More...
void | adc_register_user_callback_isr (uint32_t instance, adc_isr_callback_t func)
| Registers the custom callback function of the ADC ISR. More...

### ADC peripheral driver

# Overview

The ADC peripheral driver configures the ADC (Analog-to-Digital Converter). It handles calibration, initialization and configuration of ADC module.

# Initialization

To initialize the ADC module, call adc_init() and pass the configuration data structure. This function automatically enables the ADC module and clock. When working with advanced features, call adc_init_extend() additionally and pass the extended configuration data structure. This function enables the extended features, such as the hardware trigger, hardware average, hardware compare, low power mode, and high speed mode.

# Model building

Multiple channels share the converter, which can only serve one channel at a time. As a result the ADC channel is considered as an attribute when configuring the ADC converter instance. Therefore, when you obtain the ADC value, the value comes with the converter, after the channel is set as expected. ADC can work in three modes: Interrupt mode, Polling mode, and DMA mode. Interrupt is the recommended mode where the conversion value buffer is updated by ADC ISR. The polling mode polls the complete flag before obtaining the conversion value. The DMA mode needs the DMA support.

# Call diagram

To use the ADC driver, the user should follow these steps:

1. Execute adc_auto_calibration() to calibrate the ADC device if no other indicated offset values are used.
2. Initialize the ADC converter by calling the adc_init().
3. Initialize the advanced feature for ADC converter by calling the adc_init_extend() as needed.
4. Register the user-defined callback to ADC ISR by calling adc_register_user_callback_isr() as needed. The callback function is executed when the ADC interrupt occurs.
5. Set or reset the expected channel to a converter and execute the conversion by calling the adc_start_convertion().
6. Obtain the ADC value by calling the adc_get_conversion_value().
7. Pause the converter by calling the adc_stop_conversion() as needed.
8. Shut down the converter by calling the adc_shutdown().

This is an example code to initialize and configure the ADC driver in interrupt mode:
uint32_t val;
// Define the ADC calibration parameter variable.
adc_calibration_param_t myAdcCalParam;
// Define the ADC converter basically.
adc_user_config_t myAdcUserCfg =
{
.clockSourceMode = kAdcClockSourceAsynchrounous, // Use the ADC asynchronous clock when converting.
.clockSourceDividerMode = kAdcClockDivider8, // Set the clock divider from the bus clock.
.resolutionMode = kAdcSingleDiff16, // Conversion resolution.
.referenceVoltageMode = kAdcVoltageVref, // Reference voltage.
.isContinuousEnabled = true // Enable continuous work.
};
// Define the ADC channel.
adc_channel_config_t myAdcChannelCfg =
{
.channelId = kAdcChannelTemperature, // Set the channel ID.
.isDifferentialEnabled = false, // Use single end channel.
.isInterruptEnabled = true, // Use interrupt mode.
.groupMux = kAdcChannelMuxA // Set the group Mux.
};
// Define the ADC converter for advanced features.
adc_extend_config_t myAdcExtendCfg =
{
.isLowPowerEnabled = false, // Disable the low power mode.
.isLongSampleEnabled = true, // Enable the long sample.
.hwLongSampleMode = kAdcLongSampleDefault, // Set the long sample mode.
.isHighSpeedEnabled = false, // Disable the high speed mode.
.isAsynClockEnabled = true, // Enable the ADC asynchronous clock when initialized.
.isHwTriggerEnabled = false, // Disable the hardware trigger.
.isHwCompareEnabled = false, // Disable the hardware compare.
.isHwCompareGreaterEnabled = false, // Hardware compare related.
.isHwCompareRangeEnabled= false, // Hardware compare related.
.hwCompareValue1 = 0, // Hardware compare related.
.hwCompareValue2 = 0, // Hardware compare related.
.isHwAverageEnabled = true, // Enable the hardware average.
.hwAverageSampleMode = kAdcHwAverageCount32, // Hardware average related.
.isDmaEnabled = false // Disable the DMA switcher.
};
// Execute the auto calibration before use ADC.
adc_auto_calibration(0U, &myAdcCalParam)
// Initialize the ADC converter basically.
adc_init(0U, &myAdcUserCfg);
// Initialize the ADC additionally for extend features.
adc_init_extend(0U, &myAdcExtendCfg);
// Set the ADC channel and start conversion.
adc_start_conversion(0U, &myAdcChannelCfg);
// Get the ADC value.
val = adc_get_conversion_value(0U, &myAdcChannelCfg);
// ...
// Pause the converter.
adc_stop_conversion(0U, &myAdcChannelCfg);
// ...
// Shut down the ADC converter.
adc_shutdown(0U);

## Data Structure Documentation

struct adc_calibration_param_t

This structure keeps the calibration parameter after executing the auto-calibration or filled by indicated ones.

### Data Fields
uint32_t | PG
| The value for PG register.
uint32_t | MG
| The value for MG register.

struct adc_user_config_t

This structure is used when initializing the ADC device associated with adc_init(). It contains the basic feature configuration which are necessary.

### Data Fields
adc_clock_source_mode_t | clockSourceMode
| Selection of ADC clock source.
adc_clock_divider_mode_t | clockSourceDividerMode
| Selection of ADC clock divider.
adc_resolution_mode_t | resolutionMode
| Selection of ADC resolution.
adc_reference_voltage_mode_t | referenceVoltageMode
| Selection of ref voltage source.
bool | isContinuousEnabled
| Switcher to enable continuous conversion.

struct adc_extend_config_t

This structure is used when initializing the ADC device associated with adc_init_extend(). It contains the advanced feature configuration when necessary.

### Data Fields
bool | isLowPowerEnabled
| Switcher to enable the low power mode.
bool | isLongSampleEnabled
| Switcher to enable the long sample mode.
adc_long_sample_mode_t | hwLongSampleMode
| Selection of long sample mode.
bool | isHighSpeedEnabled
| Switcher to enable high speed sample mode.
bool | isAsynClockEnabled
| Switcher to enable internal asynchronous clock at initialization.
bool | isHwTriggerEnabled
| Switcher to enable hardware trigger.
bool | isHwCompareEnabled
| Switcher to enable hardware compare.
bool | isHwCompareGreaterEnabled
| Switcher to enable greater compare.
bool | isHwCompareRangeEnabled
| Switcher to enable range compare.
uint32_t | hwCompareValue1
| Low limit in hardware compare.
uint32_t | hwCompareValue2
| High limit in hardware compare.
bool | isHwAverageEnabled
| Switcher to enable hardware average.
adc_hw_average_mode_t | hwAverageSampleMode
| Selection of hardware average time.
bool | isDmaEnabled

struct adc_channel_config_t

This structure is used when setting the conversion channel associated with adc_start_conversion(), adc_stop_conversion(), adc_is_conversion_completed() and adc_get_conversion_value(). It contains all the information that can identify an ADC channel.

### Data Fields
adc_channel_mode_t | channelId
| Channel number.
bool | isDifferentialEnabled
| The switcher to enable differential channel.
bool | isInterruptEnabled
| The switcher to enable interrupt when conversion is completed.
adc_group_mux_mode_t | muxSelect
| Selection mux to group A(0) or group B(1)

## Typedef Documentation

typedef void(* adc_isr_callback_t)(void)

This type defines the prototype of ADC ISR callback function that can be registered inside the ISR.

## Function Documentation

adc_status_t adc_get_calibration_param | ( | uint32_t | instance,
|  | adc_calibration_param_t * | paramPtr
| ) |  |

This function is used to get the calibration parameters in auto-calibrate mode. Execute this function to obtain the parameter for the calibration during the initialization. This process may be time consuming.

Parameters

  instance | ADC instance ID.
  paramPtr | The pointer to a empty calibration parameter structure.

Returns
  The execution status.

adc_status_t adc_set_calibration_param | ( | uint32_t | instance,
|  | adc_calibration_param_t * | paramPtr
| ) |  |

This function is used to set the calibration parameters. The parameters can be generated from the auto-calibration by the adc_get_calibration_param() or created by manually indicated parameters.

Parameters

  instance | ADC instance ID.
  paramPtr | The pointer to a filled calibration parameter structure.

Returns
  The execution status.

adc_status_t adc_auto_calibration | ( | uint32_t | instance,
|  | adc_calibration_param_t * | paramPtr
| ) |  |

This function is used to execute the auto calibration. Recommended configuration has been accepted to fetch calibration parameters for highest accuracy. The calibration offset is returned to the application for further use. After the auto calibration process, the initialization function should be called explicitly to update the configuration according to the application.

Parameters

  instance | ADC instance ID.
  paramPtr | The pointer to an empty calibration parameter structure. It is filled with the calibration offset value after the function is called.

Returns
  The execution status.

adc_status_t adc_init | ( | uint32_t | instance,
|  | adc_user_config_t * | cfgPtr
| ) |  |

This function ensures that the basic operations of ADC function correctly. This function should be called when an application does not require complex features.

Parameters

  instance | ADC instance ID.
  cfgPtr | The pointer to basic configuration structure.

Returns
  The execution status.

adc_status_t adc_init_extend | ( | uint32_t | instance,
|  | adc_extend_config_t * | extendCfgPtr
| ) |  |

This function provides advanced features according when an application requires complex configurations. They are: low power mode, long sample mode, high speed mode, asynchronous work mode, hardware trigger, hardware compare, and hardware average.

Parameters

  instance | ADC instance ID.
  extendCfgPtr | The pointer to extend configuration structure.

Returns
  The execution status.

void adc_shutdown | ( | uint32_t | instance | ) |

Shutting down the ADC cuts off the clock to the indicated ADC device.

Parameters

  instance | ADC instance ID.

adc_status_t adc_start_conversion | ( | uint32_t | instance,
|  | adc_channel_config_t * | channelCfgPtr
| ) |  |

Triggers the indicated channel conversion in a single conversion mode. This function should be called when each time the conversion is triggered. In a continuous conversion mode, this function can be called only once at the beginning of conversion. The ADC executes the conversion periodically and automatically.

Parameters

  instance | ADC instance ID.
  channelCfgPtr | The pointer to channel configuration structure.

Returns
  The execution status.

adc_status_t adc_stop_conversion | ( | uint32_t | instance,
|  | adc_channel_config_t * | channelCfgPtr
| ) |  |

Stops the ADC conversion. This function sets ADC to a "NULL" channel, which stops ADC conversion from any channel. It is a different function than the adc_shutdown().

Parameters

  instance | ADC instance ID.
  channelCfgPtr | The pointer to channel configuration structure.

Returns
  The execution status.

bool adc_is_conversion_completed | ( | uint32_t | instance,
|  | adc_channel_config_t * | channelCfgPtr
| ) |  |

Checks whether the current conversion is completed. Because there are multiple channels sharing the same converter, the status is used to indicate the converter status.

Parameters

  instance | ADC instance ID.
  channelCfgPtr | The pointer to channel configuration structure.

Returns
  True if the event is asserted.

uint32_t adc_get_conversion_value | ( | uint32_t | instance,
|  | adc_channel_config_t * | channelCfgPtr
| ) |  |

The value comes from the value register that may be eventually processed according to the application. When using polling mode, the value is obtained after the conversion is completed. When using the interrupt mode, the value comes from the buffer that is updated by the ADC ISR.

Parameters

  instance | ADC instance ID.
  channelCfgPtr | The pointer to channel configuration structure.

Returns
  the value of conversion.

void adc_register_user_callback_isr | ( | uint32_t | instance,
|  | adc_isr_callback_t | func
| ) |  |

Callback provides a friendly API for application to program the ISR. A special function needs to be executed at the moment conversion is completed and can be inserted to the ISR by calling the function registered by the user.

Parameters

  instance | ADC instance ID.
  func | The pointer to user indicating callback function.