One Shot Mode - Differential Mode

This example demonstrates differential voltage detection using the ADC single sampling mode.

This example detects the differential voltage input of P2_4 and P2_5 through an interrupt. When the ADC single sampling is completed, an interrupt is triggered, and the raw data of the ADC sampling is read and converted to voltage in the interrupt function.

In this example, the ADC voltage sampling range can be selected by configuring the macro ADC_MODE_DIVIDE_OR_BYPASS.

Requirements

The sample supports the following development kits:

Development Kits

Hardware Platforms

Board Name

RTL8752H HDK

RTL8752H EVB

For more requirements, please refer to Quick Start.

Wiring

Connect P2_4 and P2_5 to the external voltage input.

Configurations

The macros that can be configured in this example are as follows:

  1. ADC_MODE_DIVIDE_OR_BYPASS : Configures the ADC voltage sampling range, with the following selectable values.

    • 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:

Project file: board\evb\io_sample\OneShotMode_DifferentialMode\mdk

Project file: board\evb\io_sample\OneShotMode_DifferentialMode\gcc

Please follow these steps to build and run the example:

  1. Open sample project file.

  2. To build the target, follow the steps listed on the Generating App Image in Quick Start.

  3. After a successful compilation, the app bin app_MP_xxx.bin will be generated in the directory mdk\bin or gcc\bin.

  4. To download app bin into EVB board, follow the steps listed on the MP Tool Download in Quick Start.

  5. Press reset button on EVB board and it will start running.

Experimental Verification

  1. 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 !

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

    [io_adc] io_adc_voltage_calculate: ADC rawdata_0 = xxx, voltage_0 = xxxmV
[io_adc] io_adc_voltage_calculate: ADC rawdata_1 = xxx, voltage_1 = xxxmV

Code Overview

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

  1. Source Code Directory.

  2. Peripheral initialization will be introduced in chapter Initialization.

  3. Functional implementation after initialization will be introduced in chapter Function Implementation.

Source Code Directory

  • Project directory: sdk\board\evb\io_sample\OneShotMode_DifferentialMode

  • Source code directory: sdk\src\sample\io_sample\OneShotMode_DifferentialMode

Source files are currently categorized into several groups as below.

└── Project: adc_one_shot_diff
    └── secure_only_app
        └── include
            ├── app_define.h
            └── rom_uuid.h
        ├── cmsis                    includes CMSIS header files and startup files
            ├── overlay_mgr.c
            ├── system_rtl876x.c
            └── startup_rtl876x.s
        ├── lib                      includes all binary symbol files that user application is built on
            ├── rtl8752h_sdk.lib
            ├── gap_utils.lib
            ├── ROM.lib
            └── adc.lib
        ├── peripheral               includes all peripheral drivers and module code used by the application
            ├── rtl876x_rcc.c
            ├── rtl876x_pinmux.c
            ├── rtl876x_nvic.c
            └── rtl876x_adc.c
        ├── profile
        └── app                      includes the ble_peripheral user application implementation
            ├── main.c
            ├── ancs.c
            ├── app.c
            ├── app_task.c
            └── io_adc.c

Initialization

When the EVB reset is initiated, the main() function is called, and the following process will be executed:

int main(void)
{
    extern uint32_t random_seed_value;
    srand(random_seed_value);
    global_data_init();
    board_init();
    le_gap_init(APP_MAX_LINKS);
    gap_lib_init();
    app_le_gap_init();
    app_le_profile_init();
    pwr_mgr_init();
    task_init();
    os_sched_start();

    return 0;
}

Note

le_gap_init(), gap_lib_init(), app_le_gap_init, and app_le_profile_init are related to the initialization of the privacy management module. Refer to the initialization process description in LE Peripheral Privacy.

The specific initialization process related to peripherals is as follows:

  1. In global_data_init, execute global_data_adc_init. This function is for global initialization and includes the following process:

    1. Execute the ADC_CalibrationInit() function for ADC calibration. If the return value is false, ADC calibration failed, possibly because the IC has not undergone FT, thus unable to accurately obtain voltage values.

    2. Initialize the global variable ADC_Global_Data.

    void global_data_adc_init(void)
{
    /* Initialize adc k value! */
    APP_PRINT_INFO0("[io_adc] global_data_adc_init");
    bool adc_k_status = false;
    adc_k_status = ADC_CalibrationInit();
    if (false == adc_k_status)
    {
        APP_PRINT_ERROR0("[io_adc] global_data_adc_init: ADC_CalibrationInit fail!");
    }
    memset(&ADC_Global_Data, 0, sizeof(ADC_Global_Data));
}

  2. In board_init, execute board_adc_init, which is responsible for PAD/PINMUX settings and includes the following process:

    1. Config PAD: Set pin as SW mode, PowerOn, internal Pull-None, disable output.

  3. After executing os_sched_start() to start task scheduling, in the app_main_task main task, execute driver_init to initialize and configure the peripheral drivers.

  4. In driver_init, execute driver_adc_init, which is the initialization function for the ADC peripheral, including the following process:

    1. Enable RCC clock.

    2. Configure ADC sampling channel, set channel 0 to P2_4 differential mode, set channel 0 to P2_5 differential mode, and set Bitmap to 0x03.

    3. If Bypass Mode is enabled, execute the function ADC_BypassCmd() to enable the Bypass mode for the corresponding pin.

    4. Configure ADC_INT_ONE_SHOT_DONE interrupt.

    5. Enable ADC sampling.

    void driver_adc_init(void)
{
    RCC_PeriphClockCmd(APBPeriph_ADC, APBPeriph_ADC_CLOCK, ENABLE);

    ADC_InitTypeDef ADC_InitStruct;
    ADC_StructInit(&ADC_InitStruct);

    ADC_InitStruct.ADC_SchIndex[0]      = EXT_DIFFERENTIAL(ADC_SAMPLE_CHANNEL_4);
    ADC_InitStruct.ADC_SchIndex[1]      = EXT_DIFFERENTIAL(ADC_SAMPLE_CHANNEL_5);

    ADC_InitStruct.ADC_Bitmap           = 0x03;
    /* Fixed 255 in OneShot mode. */
    ADC_InitStruct.ADC_SampleTime       = 255;
    ADC_Init(ADC, &ADC_InitStruct);

#if (ADC_MODE_DIVIDE_OR_BYPASS == ADC_BYPASS_MODE)
    ...
#else
    ADC_BypassCmd(0, DISABLE);
    ADC_BypassCmd(1, DISABLE);
    ADC_BypassCmd(2, DISABLE);
    ADC_BypassCmd(3, DISABLE);
    APP_PRINT_INFO0("[io_adc]driver_adc_init: ADC sample mode is divide mode !");
#endif

    ADC_INTConfig(ADC, ADC_INT_ONE_SHOT_DONE, ENABLE);

    NVIC_InitTypeDef NVIC_InitStruct;
    NVIC_InitStruct.NVIC_IRQChannel = ADC_IRQn;
    NVIC_InitStruct.NVIC_IRQChannelPriority = 3;
    NVIC_InitStruct.NVIC_IRQChannelCmd = ENABLE;
    NVIC_Init(&NVIC_InitStruct);

    ADC_Cmd(ADC, ADC_ONE_SHOT_MODE, ENABLE);
}

Functional Implementation

  1. When the ADC completes a single sampling, it triggers the ADC_INT_ONE_SHOT_DONE interrupt and enters the interrupt handler function ADC_Handler.

    1. Read the ADC sampling value.

    2. Define the message type IO_MSG_TYPE_ADC, save the collected data to a global variable, and send the message to the task.

    void ADC_Handler(void)
{
    ...
    if (ADC_GetINTStatus(ADC, ADC_INT_ONE_SHOT_DONE) == SET)
    {
        ADC_ClearINTPendingBit(ADC, ADC_INT_ONE_SHOT_DONE);

        uint16_t sample_data = 0;
        sample_data = ADC_ReadRawData(ADC, ADC_Schedule_Index_0);

        T_IO_MSG int_adc_msg;
        int_adc_msg.type = IO_MSG_TYPE_ADC;
        int_adc_msg.subtype = 0;
        ADC_Global_Data.RawDataLen = 1;
        ADC_Global_Data.RawData[0] = sample_data;
        int_adc_msg.u.buf = (void *)(&ADC_Global_Data);
        if (false == app_send_msg_to_apptask(&int_adc_msg))
        {
            APP_PRINT_ERROR0("[io_adc] ADC_Handler: Send int_adc_msg failed!");
            //Add user code here!
            ADC_ClearINTPendingBit(ADC, ADC_INT_ONE_SHOT_DONE);
            return;
        }
    }
    ...
}

  2. In the app_main_task, loop to check the message queue. When a msg is detected, execute the app_handle_io_msg function to process the msg.

  3. In the app_handle_io_msg function, if the message type is determined to be IO_MSG_TYPE_ADC, execute the io_handle_adc_msg function, and then execute io_adc_voltage_calculate.

    1. Extract the sampling data from the msg.

    2. Execute ADC_GetVoltage(), calculate the sampling voltage value based on the sampling mode, and print.

    static void io_adc_voltage_calculate(T_IO_MSG *io_adc_msg)
{
    uint8_t sample_data_len = 0;
    uint16_t sample_data[ADC_SCHEDULE_NUM] = {0};
    float sample_voltage[ADC_SCHEDULE_NUM] = {0};
    ADC_ErrorStatus error_status = NO_ERROR;

    uint16_t *p_buf = io_adc_msg->u.buf;

    sample_data_len = p_buf[0];
    for (uint8_t i = 0; i < sample_data_len; i++)
    {
        sample_data[i] = p_buf[i + 1];
        DBG_DIRECT("raw data[%d] = %d", i, sample_data[i]);
    }
    for (uint8_t i = 0; i < sample_data_len; i++)
    {

#if (ADC_MODE_DIVIDE_OR_BYPASS == ADC_BYPASS_MODE)
        sample_voltage[i] = ADC_GetVoltage(BYPASS_DIFFERENTIAL_MODE, (int32_t)sample_data[i],
                                        &error_status);
#else
        sample_voltage[i] = ADC_GetVoltage(DIVIDE_DIFFERENTIAL_MODE, (int32_t)sample_data[i],
                                        &error_status);
#endif
        if (error_status < 0)
        {
            APP_PRINT_INFO2("[io_adc]io_adc_voltage_calculate: ADC parameter or efuse data error! i = %d, error_status = %d",
                            i, error_status);
        }
        else
        {
            APP_PRINT_INFO4("[io_adc]io_adc_voltage_calculate: ADC rawdata_%-4d = %d, voltage_%-4d = %dmV ", i,
                            sample_data[i], i, (int32_t)sample_voltage[i]);
        }
    }
    memset(&ADC_Global_Data, 0, sizeof(ADC_Global_Data));
}

Troubleshooting

  1. 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!

  2. 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