2. GPADC Adapters Concept

This section explains the key features of GPADC adapters as well as the steps to enable and correctly configure the peripheral adapters for the analog-to-digital functionality. The procedure is a four-step process which can be applied to almost every type of adapter including serial peripheral adapters (I²C, SPI, UART).

Fig. 2 The Four-Step Process for Setting an Adapter Mechanism

2.1. Header Files

The header files related to adapter functionality can be found in /sdk/adapters/include. These files contain the APIs and macros for configuring the majority of the available hardware blocks. In particular, this tutorial focuses on the adapters that are responsible for the GPADC hardware block. Table 1 briefly explains the header files related to GPADC adapters (red indicates the path under which the files are stored, and green indicates which ones are used for GPADC operations).

Fig. 3 Headers for GPADC Adapters.

Table 1 Header Files used by GPADC Adapters

Filename	Description
ad_gpadc.h	This file contains APIs and macros for performing ADC operations. Use these APIs when accessing the GPADC interface to perform general-purpose conversions.
ad_battery.h	This file contains APIs and macros for performing battery measurements. Use these APIs when accessing the GPADC interface to perform battery voltage measurements.
platform_devices.h	This file contains macros for declaring virtual devices. These devices may be connected to the Dialog family of devices via a peripheral bus (for example, SPI, I2C, UART) or a peripheral hardware block (for example, GPADC).

2.2. Preparing a GPADC Operation

1. As illustrated in Fig. 4, the first step for configuring the GPADC adapter mechanism is to enable it by defining the following macros in /config/custom_config_qspi.h. Battery adapters are part of the GPADC adapter implementation and should be considered as a special analog-to-digital conversion.

/*
 * Macros for enabling GPADC + Battery measurement operations using Adapters
 */
#define dg_configUSE_HW_GPADC                   (1)
#define dg_configGPADC_ADAPTER                  (1)
#define dg_configBATTERY_ADAPTER                (1)

/*
 * This macro should be already written in the file so just make sure
 * it is set to 1
 */
#define dg_configUSE_HW_TEMPSENS                (1)

Fig. 4 First Step for Configuring the GPADC Adapter Mechanism

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

2. The second step is to declare interface parameters for all the GPADC instances. As instance can be considered a set of settings describing the complete GPADC interface. These settings are applied every time the instance is selected and used. To do this, the SDK uses a macro, named GPADC_SOURCE:

/*
 * Macro for creating an instance of the GPADC interface
 */
GPADC_SOURCE(name, _clock_source, _input_mode, input, sample_time, cancel_offset,
                                                          _oversampling,  _input_voltage)

Fig. 5 Second Step for Configuring the GPADC Adapter Mechanism

Table 2 Description of the Macro Fields Used for Declaring a GPADC Instance

Argument Name	Description
name	Declare an arbitrary alias for the GPADC interface (for instance, ADC_Channel_1). This name should be used for opening that specific instance.
_clock_source	Clock source of the GPADC controller. This can be either the internal high-speed or the system clock source. The first option selects the internal 200 MHz clock source while the second option the system clock source, that is 16 MHz or 96 MHz. Valid values are those from HW_GPADC_CLOCK enum in /sdk/peripherals/include/hw_gpadc.h.
_input_mode	This can be either single-ended or differential mode. Valid values are those from the HW_GPADC_INPUT_MODE enumerator in /sdk/peripherals/include/hw_gpadc.h.
input	The analog pin of the DA1468x chip to use for the current measurement. In contrast with the digital GPIOs, analog pins are mapped on specific pins on DA1468x SoC. Valid values are those from HW_GPADC_INPUT enum in /sdk/peripherals/include/hw_gpadc.h.
sample_time	Sampling time. Valid values are from 0 to 15. A value of 0 corresponds to one GPADC clock cycle while the maximum permitted value corresponds to 15*32 GPADC clock cycles. This parameter is application-specific and depends on the selected clock source as well as the preferred accuracy of analog-to-digital conversions.
cancel_offset	The DA1468x SoC exhibits a feature for cancelling the offset on the provided analog signals. This is done via a chopping operation where two samples with opposite signal polarity are sampled at every conversion. This feature is recommended for DC and slowly changing signals. Valid values are TRUE or FALSE.
_oversampling	In this mode, multiple successive conversions are executed and the results are added together to increase the effective number of bits. By default, the GPADC controller is a 10-bit controller and, depending on the selected oversampling, the default 10 bits can be expanded up to 16 bits. Valid values are those from HW_GPADC_OVERSAMPLING enum in /sdk/adapters/include/ad_gpadc.h.
_input_voltage	The maximum permitted analog value present on an analog pin. The GPADC controller has its own 1.2 V voltage regulator (LDO) which represents the full scale reference voltage. The GPADC controller features an attenuator capable of attenuating a signal three times, thus an analog source up to 3.6 V can also be measured. Valid values are those from HW_GPADC_INPUT_VOLTAGE enum in /sdk/adapters/include/ad_gpadc.h.

3. As illustrated in Fig. 6, the third step is the declaration of the GPADC signals.

static void prvSetupHardware( void )
{

   /* Init hardware */
   pm_system_init(periph_init)

}

Note

When the system enters sleep it loses its pin configurations. Thus, it is essential for the pins to be reconfigured to their last state as soon as the system wakes up. To do this, all pin configurations must be declared in periph_init() which is supervised by the Power Manager of the system.

Fig. 6 Third Step for Configuring the GPADC Adapter Mechanism

Note

In contrast with the digital GPIOs, analog pins are mapped on specific pins on the DA1468x SoC.

4. Having enabled the GPADC adapter mechanism, the developer is able to use all the available APIs for performing analog-to-digital conversions. The following describes the required sequence of APIs in an application to successfully execute GPADC operations.

Fig. 7 Fourth Step for Configuring the GPADC Adapter Mechanism

1. ad_gpadc_init() or GPADC_INIT()

   Must be called once at either platform start (for instance, in system_init()) or task initialization to perform all the necessary initialization routines.

2. ad_gpadc_open()

   Before using a GPADC instance, the application task must first open it. The function returns a handler to the main flow for use in subsequent adapter functions. Subsequent calls from other tasks simply return the existing handler.

3. ad_gpadc_acquire()

   This API is optional since it is automatically called upon a GPADC operation and it is used for locking the GPADC block for the given opened instance. This function should be called when the application task wants to communicate to the GPADC block directly using low level drivers.

Note

This function can be called several times. It is essential that the number of ad_gpadc_acquire() calls matches the number of ad_gpadc_release() calls.

4. Perform analog-to-digital operations either synchronously or asynchronously.

   After opening an instance, the application task(s) can perform any analog-to-digital conversion either synchronously or asynchronously. Please note that all the available APIs for accessing the GPADC interface, nest the corresponding APIs for acquiring and releasing the GPADC block.

5. ad_gpadc_release()

   This function must be called for each call to ad_gpadc_acquire().

6. ad_gpadc_close()

   After all user operations are done and the interface is no longer needed, it should be closed by the task that has currently acquired it. The application can then switch to other GPADC instances (as needed). Remember that GPADC adapter implementation follows a single instance scheme, that is only one instance can be opened at a time.

2.3. Battery Adapters

Battery voltage measurements can be considered as a special use case of the GPADC interface. The DA1468x chip has a dedicated analog pin internally connected to the terminals of the DA1468x daughterboard’s battery holder. The SDK comes with additional APIs responsible for executing battery voltage measurements and it is recommended that the user should use these APIs when accessing the GPADC controller to perform such an operation.

1. ad_gpadc_init() or GPADC_INIT()

   Must be called once at either platform start (for instance, system_init()) or task initialization to perform all the necessary initialization routines.

2. ad_battery_open()

   Before using the battery instance the application task must first open it. In contrast with the ad_gpadc_open() API, this function has no input parameters since it is considered that only one interface is defined for battery voltage measurements.

Note

The function calls the ad_gpadc_open() API using the BATTERY_LEVEL id which is the default id for the battery interface configurations (declared in platform_devices.h).

3. Perform a battery voltage measurement either synchronously or asynchronously.

   • To perform synchronous measurements, use the ad_battery_read() function. This function waits until the GPADC controller becomes available.
   • To perform asynchronous measurements, use the ad_battery_read_async() function. When an analog-to-digital conversion is finished, a callback function is called and the results of the conversion are available within this callback.

4. ad_battery_raw_to_mvolt()

   After performing a successful analog-to-digital conversion, the developer can use this function to convert the raw ADC value to millivolts (mV).

6. ad_battery_close()

   After all user operations are done and the interface is no longer needed, it should be closed by the task that has currently acquired it.

2.4. 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 Fig. 8. The 0 V to 5 V range is divided into 2¹⁰ = 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.

Fig. 8 Analog-to-Digital Conversion Process

Fig. 9 depicts the relationship between analog and raw ADC values.

Fig. 9 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 Fig. 10

Fig. 10 Resulting Raw ADC Value