One Shot Interrupt

This sample application note describes voltage detection by using the ADC One Shot Interrupt mode.

The example can use the macro ADC_DATA_OUTPUT_TO_FIFO to configure whether or not to store the ADC samples into the FIFO.

The example macro to configure the ADC sample voltage range includes Divide Mode and Bypass Mode.

When the ADC sampling is finished, the ADC_INT_ONE_SHOT_DONE or ADC_INT_FIFO_THD interrupt is triggered, which reads the raw data and calculates the voltage conversion within the interrupt function.

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

Connect P2_4 to external voltage input.

Configurations

The example configurable macros are as follows:

ADC_DATA_OUTPUT_TO_FIFO : select whether the ADC sample value is stored in FIFO, 1 means the ADC sample data is stored in FIFO, 0 means the ADC data is stored in Schedule Table.
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_interrupt\proj\rtl87x2g\mdk

GCC

Project file: samples\peripheral\adc\oneshot_interrupt\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 EVB starts, observe the following log within the Debug Analyzer
```
Start ADC interrupt 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 sampling by the ADC, print the raw data obtained from sampling and the converted voltage value within the interrupt function.
```
into SAR_ADC_Handler
[ADC] adc_sample_demo: ADC one shot mode sample data = xxx, voltage = 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_interrupt\proj
Source Code Directory: sdk\samples\peripheral\adc\oneshot_interrupt\src

Source files are currently categorized into several groups as below.

└── Project: oneshot_interrupt
    └── 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_nvic.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 low level.

driver_adc_init contains the initialization of the ADC peripheral.

Enable PCC clock.
Config ADC sample channel, channel 0 of the ADC selects pin P2_4 of the ADC single-ended mode, the corresponding bitmap is 0x01.
If enable the macro ADC_DATA_OUTPUT_TO_FIFO, set ADC_DataWriteToFifo to ENABLE and config FIFO Threshold Level.
If configured as bypass mode, execute ADC_BypassCmd() to enable the high resistance mode of the corresponding channel.
Config ADC interrupt:
- If enabling the macro ADC_DATA_OUTPUT_TO_FIFO, config ADC_INT_FIFO_THD interrupt.
- If disabling the macro ADC_DATA_OUTPUT_TO_FIFO, config ADC_INT_ONE_SHOT_DONE interrupt.

  RCC_PeriphClockCmd(APBPeriph_ADC, APBPeriph_ADC_CLOCK, ENABLE);
  ...
  /* Configure the ADC sampling schedule0 */
  ADC_InitStruct.ADC_SchIndex[0]      = EXT_SINGLE_ENDED(ADC_SAMPLE_CHANNEL);
  /* Set the bitmap corresponding to schedule0*/
  ADC_InitStruct.ADC_Bitmap           = 0x01;

#if (ADC_DATA_OUTPUT_TO_FIFO)
  ADC_InitStruct.ADC_DataWriteToFifo  = ENABLE;
  ADC_InitStruct.ADC_FifoThdLevel     = 0x0A;
#endif
  ...
#if (!ADC_DATA_OUTPUT_TO_FIFO)
  ADC_INTConfig(ADC, ADC_INT_ONE_SHOT_DONE, ENABLE);
#else
  ADC_INTConfig(ADC, ADC_INT_FIFO_THD, ENABLE);
#endif

Functional Implementation

If enabling the macro ADC_DATA_OUTPUT_TO_FIFO, execute ADC_ClearFIFO() before ADC sampling to clear data in ADC FIFO.
Cyclically execute ADC_Cmd(), start ADC sampling.
When the ADC single conversion is completed, trigger the interrupt and enter the interrupt handler function.
If enabling the macro ADC_DATA_OUTPUT_TO_FIFO, execute ADC_GetFIFODataLen() to read ADC FIFO data length, execute ADC_ReadFIFOData() to store ADC FIFO data.
If disabling the macro ADC_DATA_OUTPUT_TO_FIFO, execute ADC_ReadRawData() to read ADC sample data.
Execute ADC_GetVoltage() to calculate the sample voltage based on the sample data.
If enabling the macro ADC_DATA_OUTPUT_TO_FIFO, execute ADC_ClearFIFO() to clear ADC FIFO after reading ADC FIFO.

#if (!ADC_DATA_OUTPUT_TO_FIFO)
  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);

#else
  if (ADC_GetINTStatus(ADC, ADC_INT_FIFO_THD) == SET)
  {
    uint16_t data_len = ADC_GetFIFODataLen(ADC);
    ADC_ReadFIFOData(ADC, sample_data, data_len);
    for (uint8_t i = 0; i < data_len; i++)
    {
        sample_voltage[i] = ADC_GetVoltage(DIVIDE_SINGLE_MODE, (int32_t)sample_data[i], &error_status);
    }
    ...
    ADC_ClearFIFO(ADC);
  }
#endif

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