One Shot Polling

This sample describes voltage detection by using the ADC One Shot Polling mode.

The sample uses macros to configure the ADC sampling mode and sampling voltage range.

The sampling modes include Hardware Average sampling and Differential Mode sampling in addition to normal ADC sampling.

The sampling voltage range includes Divide Mode and Bypass Mode.

ADC sampling is performed with the polling ADC_INT_ONE_SHOT_DONE interrupt. When sampling completion is detected, the raw data is read and voltage conversion is calculated.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

For more requirements, please refer to Quick Start.

Wiring

If ADC_DEMO_MODE is set to ADC_DEMO_POLLING or ADC_DEMO_AVERAGE :
Connect P2_4 to external voltage input.
If ADC_DEMO_MODE is set to ADC_DEMO_DIFFERENTIAL :
Connect P2_6 to P port of external voltage input, P2_7 to N port of external voltage input.

Configurations

The example configurable macros are as follows:

ADC_DEMO_MODE : select the sampling method of the ADC, and the selectable values are as follows:
- ADC_DEMO_POLLING : ADC Normal Polling Mode Sampling. In this mode, all 16 channels sample the voltage of P2_4.
- ADC_DEMO_AVERAGE : ADC Hardware Average Sampling. In this mode, only channel 0 samples the voltage of P2_4.
- ADC_DEMO_DIFFERENTIAL : ADC Differential Mode Sampling. In this mode, channel 0 and channel 1 sample the differential voltages of P2_6 and P2_7.
ADC_MODE_DIVIDE_OR_BYPASS : Selects the voltage sampling range of the ADC, and the selectable values are as follows:
- ADC_DIVIDE_MODE : In Divide Mode, the ADC samples voltage values ranging from 0 to 3.3V.
- ADC_BYPASS_MODE : In Bypass Mode, the ADC samples voltage values ranging from 0 to 0.9V.

Building and Downloading

This sample can be found in the SDK folder:

Keil

Project file: samples\peripheral\adc\oneshot_polling\proj\rtl87x2g\mdk

GCC

Project file: samples\peripheral\adc\oneshot_polling\proj\rtl87x2g\gcc

To build and run the sample, follow the steps listed below:

Open sample project file.
To build the target, follow the steps listed on the Generating App Image in Quick Start.
After a successful compilation, the app bin app_MP_xxx.bin will be generated in the directory mdk\bin or gcc\bin.
To download app bin into EVB board, follow the steps listed on the MP Tool Download in Quick Start.
Press reset button on EVB board and it will start running.

Experimental Verification

When the IC starts, observe the following log within the Debug Analyzer.
```
Start adc polling test!
```
ADC Configurations:
1. If the ADC is configured as ADC_DIVIDE_MODE, print the following log.
```
[ADC]ADC sample mode is divide mode !
```
2. If the ADC is configured as ADC_BYPASS_MODE, print the following log.
```
[ADC]ADC sample mode is bypass mode !
```

After the ADC sampling is finished, the raw data acquired and the converted voltage values are printed within the Debug Analyzer.

[ADC] adc_sample_demo: ADC one shot mode sample data_0 = xxx, voltage_0 = xxx mV
...
[ADC] adc_sample_demo: ADC one shot mode sample data_15 = xxx, voltage_15 = xxx mV

Code Overview

This chapter will be introduced according to the following several parts:

Source Code Directory.
Peripheral initialization will be introduced in chapter Initialization.
Functional implementation after initialization will be introduced in chapter Functional Implementation.

Source Code Directory

Project directory: sdk\samples\peripheral\adc\oneshot_polling\proj
Source code directory: sdk\samples\peripheral\adc\oneshot_polling\src

Source files are currently categorized into several groups as below.

└── Project: oneshot_polling
    └── secure_only_app
        └── Device                   includes startup code
            ├── startup_rtl.c
            └── system_rtl.c
        ├── CMSIS                    includes CMSIS header files
        ├── CMSE Library             Non-secure callable lib
        ├── lib                      includes all binary symbol files that user application is built on
            └── rtl87x2g_io.lib
        ├── peripheral               includes all peripheral drivers and module code used by the application
            ├── rtl_rcc.c
            ├── rtl_pinmux.c
            └── rtl_adc.c
        └── APP                      includes the ble_peripheral user application implementation
            ├── main_ns.c
            └── io_adc.c

Initialization

The initialization process includes: board_adc_init and driver_adc_init.

board_adc_init contains the PAD settings.

Set pin as SW mode, PowerOn, internal Pull-None, disable output, output high level.
1. If ADC_DEMO_MODE is set to ADC_DEMO_POLLING or ADC_DEMO_AVERAGE, set pin to P2_4.
2. If ADC_DEMO_MODE is set to ADC_DEMO_DIFFERENTIAL, set pin to P2_6 and P2_7.

driver_adc_init contains the initialization of ADC peripherals.

Config ADC sample channel.
1. If ADC_DEMO_MODE is set to ADC_DEMO_POLLING, all 16 ADC channels select ADC single-ended pin P2_4, the corresponding bitmap is 0xFFFF.
2. If ADC_DEMO_MODE is set to ADC_DEMO_AVERAGE, channel 0 of the ADC selects pin P2_4 of the ADC single-ended mode, the corresponding bitmap is 0x01, set data average number to 4.
3. If ADC_DEMO_MODE is set to ADC_DEMO_DIFFERENTIAL, channel 0 and channel 1 of the ADC are configured to use the ADC differential mode, with pin P2_6 and P2_7 selected as input for channel 0 and channel 1 respectively, the corresponding bitmap is 0x03.
If configured as bypass mode, execute ADC_BypassCmd() to enable the high resistance mode of the corresponding channel.
Enable ADC_INT_ONE_SHOT_DONE interrupt.

#if (ADC_DEMO_MODE == ADC_DEMO_POLLING)
    for (uint8_t i = 0; i < 16; i++)
    {
        ADC_InitStruct.ADC_SchIndex[i]  = EXT_SINGLE_ENDED(ADC_SAMPLE_CHANNEL);
    }
    ADC_InitStruct.ADC_Bitmap           = 0xFFFF;
#elif (ADC_DEMO_MODE == ADC_DEMO_AVERAGE)
    ADC_InitStruct.ADC_SchIndex[0]      = EXT_SINGLE_ENDED(ADC_SAMPLE_CHANNEL);
    ADC_InitStruct.ADC_DataAvgEn        = ENABLE;
    ADC_InitStruct.ADC_DataAvgSel       = ADC_DATA_AVERAGE_OF_4;
    ADC_InitStruct.ADC_Bitmap           = 0x01;
#elif (ADC_DEMO_MODE == ADC_DEMO_DIFFERENTIAL)
    ADC_InitStruct.ADC_SchIndex[0]      = EXT_DIFFERENTIAL(ADC_SAMPLE_CHANNEL_0);
    ADC_InitStruct.ADC_SchIndex[1]      = EXT_DIFFERENTIAL(ADC_SAMPLE_CHANNEL_1);
    ADC_InitStruct.ADC_Bitmap           = 0x03;
#endif

Note

For Average mode of ADC, it applies only to channel 0, other channels cannot be sampled with ADC Average.

Functional Implementation

Execute ADC_Cmd() to start ADC one-shot sampling.
In adc_sample_demo, check conversion completion interrupt state in a while loop until its value is SET, indicating that the conversion is complete.
Execute ADC_ReadRawData() to read ADC sample data.
Execute ADC_GetVoltage() to calculate the sample voltage based on the sample data.

while (ADC_GetINTStatus(ADC, ADC_INT_ONE_SHOT_DONE) == RESET) {}
ADC_ClearINTPendingBit(ADC, ADC_INT_ONE_SHOT_DONE);
...
sample_data[i] = ADC_ReadRawData(ADC, ADC_Schedule_Index_0 + i);
sample_voltage[i] = ADC_GetVoltage(DIVIDE_SINGLE_MODE, (int32_t)sample_data[i], &error_status);

Note

If ADC_DEMO_MODE is set to ADC_DEMO_AVERAGE, it needs to take out the integer part of the sampled data for voltage conversion, and the decimal part does not support voltage conversion.

Troubleshooting

If the IC obtained has not been verified by FT, the ADC will not be able to convert to the correct voltage value. The following message will be printed within the log tool.
```
[ADC]ADC_CalibrationInit fail!
```

If the ADC sample value is incorrect, print the error status.

[ADC]adc_sample_demo: ADC parameter or efuse data error! i = xxx, error_status = xxx