/**
 * @file adcs.h
 * @brief Header file for ADC driver using LL library.
 *
 * This file contains the declarations and documentation for the ADC driver
 * using the LL (Low-Level) library.
 *
 * @date 2023-09-04 15:59:16
 * @author xxx
 * @version 1.0
 *
 * @note This code is proprietary and confidential.
 * Unauthorized copying of this file, via any medium is strictly prohibited.
 *
 * @note All rights reserved by xxx.
 */

#ifndef __ADCS_H__
#define __ADCS_H__
#include "sys.h"

#define ADC_CHANNEL_MAX 18 ///< Maximum number of ADC channels
typedef enum
{
    IN0 = BIT0,
    IN1 = BIT1,
    IN2 = BIT2,
    IN3 = BIT3,
    IN4 = BIT4,
    IN5 = BIT5,
    IN6 = BIT6,
    IN7 = BIT7,
    IN8 = BIT8,
    IN9 = BIT9,
    IN10 = BIT10,
    IN11 = BIT11,
    IN12 = BIT12,
    IN13 = BIT13,
    IN14 = BIT14,
    IN15 = BIT15,
    IN16 = BIT16,
    INTEMP = BIT17,
    INVBAT = BIT18,
    INVREF = BIT19,
} adc_num_e; ///< ADC channel number

typedef enum
{
    ADCS_1,
    ADCS_2,
    ADCS_3,
    ADCS_MAX,
} adcs_e; ///< ADC number

typedef union
{
    uint32_t data;
    struct
    {
        uint32_t in0 : 1;
        uint32_t in1 : 1;
        uint32_t in2 : 1;
        uint32_t in3 : 1;
        uint32_t in4 : 1;
        uint32_t in5 : 1;
        uint32_t in6 : 1;
        uint32_t in7 : 1;
        uint32_t in8 : 1;
        uint32_t in9 : 1;
        uint32_t in10 : 1;
        uint32_t in11 : 1;
        uint32_t in12 : 1;
        uint32_t in13 : 1;
        uint32_t in14 : 1;
        uint32_t in15 : 1;
        uint32_t invref : 1;
        uint32_t intemp : 1;
    };
} adcs_channels_u; ///< ADC channels

typedef struct
{
    ADC_TypeDef *adc;         ///< ADC peripheral
    DMA_TypeDef *dma;         ///< DMA peripheral
    uint32_t dma_stream;      ///< DMA stream
    uint32_t dma_channel;     ///< DMA channel
    adcs_channels_u channels; ///< ADC channels
    uint32_t ovr_count;       ///< ADC overflow count

    uint16_t adc_cct;         ///< Channel single acquisition count
    uint8_t adc_chans_count;  ///< Number of channels
    uint16_t adc_sum;         ///< Channel acquisition count
    __IO uint16_t *adc_value; ///< Address to store ADC conversion results

} adcs_t;

/**
 * @brief Initializes the ADC module.
 *
 * This function initializes the ADC module with the specified parameters.
 *
 * @param num The ADC number.
 * @param adc Pointer to the ADC peripheral.
 * @param dma Pointer to the DMA peripheral.
 * @param dma_channel The DMA channel number.
 * @param adc_cct The ADC continuous conversion mode.
 * @param channels The number of ADC channels to be converted.
 */
extern void adc_init(adcs_e num, ADC_TypeDef *adc, DMA_TypeDef *dma, uint32_t dma_stream, uint32_t dma_channel, uint16_t adc_cct, uint32_t channels);

/**
 * @brief Starts the ADC conversion.
 *
 * This function starts the ADC conversion for the specified ADC number.
 *
 * @param num The ADC number.
 */
extern void adc_restart(adcs_e num);

/**
 * @brief Deinitializes the ADC module.
 *
 * This function deinitializes the ADC module.
 *
 * @param num The ADC number.
 */
extern void adc_dinit(adcs_e num);

/**
 * @brief Gets the ADC conversion result for a single channel.
 *
 * This function gets the ADC conversion result for a single channel.
 * It returns only the first converted value.
 *
 * @param num The ADC number.
 * @param chan The ADC channel number.
 * @return The ADC conversion result.
 */
extern uint16_t adc_result_only_one(adcs_e num, uint8_t chan);

/**
 * @brief Gets the ADC conversion result using median average filtering.
 *
 * This function gets the ADC conversion result for a single channel.
 * It applies median average filtering to the converted values.
 *
 * @param num The ADC number.
 * @param chan The ADC channel number.
 * @return The ADC conversion result.
 */
extern uint16_t adc_result_median_average(adcs_e num, uint8_t chan);

/**
 * @brief Gets the ADC conversion result using median filtering.
 *
 * This function gets the ADC conversion result for a single channel.
 * It applies median filtering to the converted values.
 *
 * @param num The ADC number.
 * @param chan The ADC channel number.
 * @return The ADC conversion result.
 */
extern uint16_t adc_result_median(adcs_e num, uint8_t chan);

/**
 * @brief Gets the ADC conversion result using average filtering.
 *
 * This function gets the ADC conversion result for a single channel.
 * It applies average filtering to the converted values.
 *
 * @param num The ADC number.
 * @param chan The ADC channel number.
 * @return The ADC conversion result.
 */
extern uint16_t adc_result_average(adcs_e num, uint8_t chan);

/**
 * @brief Gets the ADC conversion result using N-times average filtering.
 *
 * This function gets the ADC conversion result for a single channel.
 * It applies N-times average filtering to the converted values.
 *
 * @param num The ADC number.
 * @param chan The ADC channel number.
 * @return The ADC conversion result.
 */
extern uint16_t adc_result_n_average(adcs_e num, uint8_t chan);

/**
 * @brief Calculates the temperature from the ADC conversion result.
 *
 * This function calculates the temperature in degrees Celsius
 * from the ADC conversion result of the internal temperature sensor.
 *
 * @param adc_value The ADC conversion result.
 * @return The temperature in degrees Celsius.
 */
extern float32 adc_result_temperature(uint16_t adc_value);

/**
 * @brief Calculates the voltage from the ADC conversion result.
 *
 * This function calculates the voltage in millivolts
 * from the ADC conversion result of the internal voltage reference.
 *
 * @param adc_value The ADC conversion result.
 * @return The voltage in millivolts.
 */
extern float32 adc_result_value_local(uint16_t adc_value);

/**
 * @brief ADC environment callback function.
 *
 * This function is called when an ADC conversion is completed.
 *
 * @param num The ADC number.
 */
extern void adc_env_callback(adcs_e num);

/**
 * @brief DMA callback function for ADC.
 *
 * This function is called when a DMA transfer for ADC is completed.
 *
 * @param num The ADC number.
 */
extern void adc_dma_callback(adcs_e num);
#endif ///< __ADCS_H__