1# ADC 2 3## Overview 4 5### Function 6 7An analog-to-digital converter (ADC) converts analog signals into digital signals for storage and computing. In addition to the power cable and ground cable, the ADC requires only one cable to connect to the target device. The following figure shows the physical connection of the ADC. 8 9**Figure 1** ADC physical connection 10 11 12 13The ADC module provides a set of APIs to complete AD conversion, including: 14 15- Opening or closing an ADC device 16- Obtaining the analog-to-digital (AD) conversion result 17 18### Basic Concepts 19 20- Resolution 21 22 The number of binary bits that can be converted by an ADC. A greater number of bits indicates a higher resolution. 23 24- Conversion error 25 26 Difference between the actual and theoretical digital values output by an ADC. It is expressed by a multiple of the least significant bit. Generally, the maximum output error is used. 27 28- Transition time 29 30 Time required by an ADC to perform a complete conversion. 31 32### Working Principles 33 34In the Hardware Driver Foundation (HDF), the ADC module uses the unified service mode for API adaptation. In this mode, a service is used as the ADC manager to handle external access requests in a unified manner. The unified service mode applies when the system has multiple device objects of the same type. If the independent service mode is used in this case, more device nodes need to be configured and more memory resources will be consumed. 35 36### Constraints 37 38The ADC module can read data only in polling mode. 39 40## Usage Guidelines 41 42### When to Use 43 44ADC devices are used to convert analog voltage or current into digital parameters. For example, an ADC can be used with an NTC resistor to measure temperature, or can be used to convert the output of an analog sensor into a digital parameter. 45 46### Available APIs 47 48The following table describes the APIs of the ADC module. For more information, see **//drivers/hdf_core/framework/include/platform/adc_if.h**. 49 50**Table 1** APIs of the ADC driver 51 52| API | Description | 53| -------- | ---------------- | 54| DevHandle AdcOpen(uint32_t number) | Opens an ADC device. | 55| void AdcClose(DevHandle handle) | Closes an ADC device. | 56| int32_t AdcRead(DevHandle handle, uint32_t channel, uint32_t \*val) | Obtains the AD conversion result.| 57 58### How to Develop 59 60The following figure illustrates how to use ADC APIs. 61 62 **Figure 2** Process of using ADC APIs 63 64 65 66 67#### Opening an ADC Device 68 69Call **AdcOpen()** to open an ADC device. 70 71```c 72DevHandle AdcOpen(int16_t number); 73``` 74 75**Table 2** Description of AdcOpen 76 77| Parameter | Description | 78| ---------- | ----------------- | 79| number | ADC device number. | 80| **Return Value**| **Description** | 81| NULL | The operation fails. | 82| Device handle | The operation is successful. The handle of the ADC device opened is returned.| 83 84Example: Open device 1 of the two ADCs (numbered 0 and 1) in the system. 85 86```c 87DevHandle adcHandle = NULL; /* ADC device handle / 88 89/* Open ADC device 1. */ 90adcHandle = AdcOpen(1); 91if (adcHandle == NULL) { 92 HDF_LOGE("AdcOpen: fail\n"); 93 return; 94} 95``` 96 97#### Obtaining the AD Conversion Result 98 99```c 100int32_t AdcRead(DevHandle handle, uint32_t channel, uint32_t *val); 101``` 102 103**Table 3** Description of AdcRead 104 105| Parameter | Description | 106| ---------- | -------------- | 107| handle | ADC device handle. | 108| channel | ADC device channel number. | 109| val | Pointer to the AD conversion result. | 110| **Return Value**| **Description**| 111| 0 | The operation is successful. | 112| Negative value | The operation fails. | 113 114Example: Obtain the AD conversion result of channel 1. 115 116```c 117uint32_t value; 118int32_t ret; 119 120ret = AdcRead(adcHandle, 1, &value); 121if (ret != 0) { 122 HDF_LOGE("ADC read fail!\n"); 123 return; 124} 125``` 126 127#### Closing an ADC Device 128 129Call **AdcClose()** to close the ADC device after the ADC communication is complete. 130```c 131void AdcClose(DevHandle handle); 132``` 133**Table 4** Description of AdcClose 134 135| Parameter | Description | 136| ------ | ----------- | 137| handle | ADC device handle.| 138| **Return Value**| **Description** | 139| N/A | N/A | 140 141Example: 142 143```c 144AdcClose(adcHandle); /* Close the ADC device. */ 145``` 146 147### Example 148 149The following example shows how to use ADC APIs to manage an ADC device on a Hi3516D V300 board. 150 151The hardware information is as follows: 152 153- SoC: hi3516dv300 154 155- The potentiometer is connected to channel 1 of ADC 0. 156 157Perform continuous read operations on the ADC device to check whether the ADC is functioning. 158 159Example: 160 161```c 162#include "adc_if.h" /* Header file for ADC APIs */ 163#include "hdf_log.h" /* Header file for log APIs */ 164 165/* Define device 0, channel 1. */ 166#define ADC_DEVICE_NUM 0 167#define ADC_CHANNEL_NUM 1 168#define ADC_TEST_NUM 30 169 170/* Main entry of ADC routines. */ 171static int32_t TestCaseAdc(void) 172{ 173 int32_t i; 174 int32_t ret; 175 DevHandle adcHandle = NULL; 176 uint32_t readBuf[ADC_TEST_NUM] = {0}; 177 178 /* Open the ADC device. */ 179 adcHandle = AdcOpen(ADC_DEVICE_NUM); 180 if (adcHandle == NULL) { 181 HDF_LOGE("%s: Open ADC%u fail!", __func__, ADC_DEVICE_NUM); 182 return -1; 183 } 184 185 /* Perform 30 times of AD conversions continuously and read the conversion results. */ 186 for (i = 0; i < ADC_TEST_NUM; i++) { 187 ret = AdcRead(adcHandle, ADC_CHANNEL_NUM, &readBuf[i]); 188 if (ret != HDF_SUCCESS) { 189 HDF_LOGE("%s: ADC read fail!:%d", __func__, ret); 190 AdcClose(adcHandle); 191 return -1; 192 } 193 } 194 HDF_LOGI("%s: ADC read successful!", __func__); 195 196 /* Close the ADC device. */ 197 AdcClose(adcHandle); 198 199 return 0; 200} 201``` 202
