2. GPADC Adapters Concept

This section explains the procedure to enable and correctly configure the peripheral adapters for GPADC functionality. The procedure is a three-step process which can be applied to almost every type of adapter including serial peripheral adapters (I2C, SPI, UART).

'The Three-Step Process for Setting the GPADC Adapter Mechanism'

Figure 1 The Three-Step Process for Setting the GPADC Adapter Mechanism

2.1. Preparing the GPADC Adapter

  1. The first step for configuring the GPADC adapter mechanism is to enable it by defining the following macros in /config/custom_config_xxx.h file:

/*
 * Macros for enabling I2C operations using Adapters
 */
#define dg_configUSE_HW_GPADC                     (1)
#define dg_configGPADC_ADAPTER                    (1)

From this point onwards, the overall adapter implementation with all its integrated functions is available.

  1. The second step is to declare IO bus as well as driver configurations for all the analog devices connected on the GPADC block. These settings are applied every time the analog device is selected and used. All the configurations should be placed in platform_devices.c file.

  2. Once the GPADC adapter mechanism is enabled, the developer can use all the available APIs for performing GPADC operations. The following steps describe the required sequence of APIs in an application to successfully execute a GPADC operation.

    1. ad_gpadc_init()

      This must be called once at either platform start (system_init()) or task initialization to perform all the necessary GPADC initialization routines.

    2. ad_gpadc_open()

      Before using the GPADC interface, the application task must open the device that will access the GPADC block. Opening a device involves acquiring all the required resources as well as configuring the GPADC controller with the target device and IO bus settings. This function returns a handler to the main flow for use in subsequent adapter functions. Note that this function will block until it acquires all controller resources.

    3. Perform a write/read transaction either synchronously or asynchronously.

      After opening a device, the application task can perform any GPADC operation either synchronously or asynchronously. In synchronous mode, the calling task is blocked for the duration of the GPADC operation but other tasks are not. In asynchronous mode, the calling task is not blocked by the GPADC operation and thus the application task can continue with other operations while waiting for a user-defined callback function to be called, signaling the completion of the GPADC operation.

      • User-defined callback functions are called from within Interrupt Service Routine (ISR) context. Therefore, callback’s execution time should be as short as possible and not contain complex calculations. Please note that for as long as a system interrupt is serviced, the main application is halted.

      • Do not call asynchronous related APIs consecutively without guaranteeing that the previous asynchronous transaction is finished.

    1. ad_gpadc_close()

      After all user operations are done and the device is no longer needed, it should be closed. This step involves disabling and de-initializing the GPADC block used as well as releasing all the previously acquired resources.

Note

For more detailed information on the GPADC APIs please refer to sdk\adapters\include\ad_template.h file.

2.2. Handling ADC Measurements

This section describes the basic operation principles of the ADC controller and how to handle the resulting data upon a successful analog-to-digital conversion.

Consider an ADC controller with a voltage reference of 5 V and a resolution of 10 bits, that is, it has the ability to detect 1024 discrete analog levels. In this case, any analog value in between 0 V and 5 V is converted into its equivalent ADC value as shown in Figure 2. The 0 V to 5 V range is divided into 210 = 1024 steps. Thus, a 0 V input results in an ADC output of 0, a 5 V input gives an ADC value equal to 1023, and a 2.5 V input results in an ADC output of around 512.

'Analog-to-Digital Conversion Process'

Figure 2 Analog-to-Digital Conversion Process

Figure 3 depicts the relationship between analog and raw ADC values.

'Basic Relationship Between Analog and Raw ADC Values'

Figure 3 Basic Relationship between Analog and Raw ADC Values

The resolution of the ADC controller is dependent on the oversampling used. GPADC adapters come with the following API which returns the ADC resolution depending on the selected oversampling: ad_gpadc_get_source_max(). Possible returned values are: 0x3FF (10 bits), 0x7FF (11 bits), 0xFFF (12 bits), 0x1FFF (13 bits), 0x3FFF (14 bits) 0x7FFF (15 bits), or 0xFFFF (16 bits)

Following is an example which demonstrates the computation of the raw ADC value for an analog input source of 3.05V. As described, the ADC voltage reference can be the default 1.2 V or 3.6 V when 3X attenuator is selected, or 5 V in the case of the VBAT channel. Assuming the VBAT channel is selected and the oversampling results in 12-bit resolution, the raw ADC value can be easily computed as illustrated in Figure 4

'Resulting raw ADC value'

Figure 4 Resulting Raw ADC Value