EspAdc.h

Go to the documentation of this file.

 
#pragma once
 
#include "McuSelect.h"
 
// Only compile for ESP32 family
#ifdef HF_MCU_FAMILY_ESP32
 
#include "BaseAdc.h"
#include "PlatformMutex.h"
#include "utils/EspTypes.h"
 
#include <array>
#include <atomic>
#include <memory>
#include <vector>
 
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
 
#include "driver/gpio.h"
#include "esp_adc/adc_cali.h"
#include "esp_adc/adc_cali_scheme.h"
#include "esp_adc/adc_continuous.h"
#include "esp_adc/adc_filter.h"
#include "esp_adc/adc_monitor.h"
#include "esp_adc/adc_oneshot.h"
#include "esp_log.h"
#include "esp_timer.h"
 
#ifdef __cplusplus
}
#endif
 
#include "PlatformMutex.h"
 
//==============================================================================
// ESP32 VARIANT-SPECIFIC ADC CONFIGURATION
//==============================================================================
 
// ESP32-C6 Configuration
#if defined(HF_MCU_ESP32C6)
#define HF_ESP32_ADC_MAX_UNITS 1                  
#define HF_ESP32_ADC_MAX_CHANNELS 7               
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 100000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// ESP32 Classic Configuration
#elif defined(HF_MCU_ESP32)
#define HF_ESP32_ADC_MAX_UNITS 2                  
#define HF_ESP32_ADC_MAX_CHANNELS 8               
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 200000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_RTC_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// ESP32-S2 Configuration
#elif defined(HF_MCU_ESP32S2)
#define HF_ESP32_ADC_MAX_UNITS 1                  
#define HF_ESP32_ADC_MAX_CHANNELS 10              
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 200000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_RTC_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// ESP32-S3 Configuration
#elif defined(HF_MCU_ESP32S3)
#define HF_ESP32_ADC_MAX_UNITS 2                  
#define HF_ESP32_ADC_MAX_CHANNELS 10              
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 200000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_RTC_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// ESP32-C3 Configuration
#elif defined(HF_MCU_ESP32C3)
#define HF_ESP32_ADC_MAX_UNITS 1                  
#define HF_ESP32_ADC_MAX_CHANNELS 6               
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 100000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_RTC_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// ESP32-C2 Configuration
#elif defined(HF_MCU_ESP32C2)
#define HF_ESP32_ADC_MAX_UNITS 1                  
#define HF_ESP32_ADC_MAX_CHANNELS 4               
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 100000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_RTC_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// ESP32-H2 Configuration
#elif defined(HF_MCU_ESP32H2)
#define HF_ESP32_ADC_MAX_UNITS 1                  
#define HF_ESP32_ADC_MAX_CHANNELS 6               
#define HF_ESP32_ADC_MAX_FILTERS 2                
#define HF_ESP32_ADC_MAX_MONITORS 2               
#define HF_ESP32_ADC_MAX_RAW_VALUE 4095           
#define HF_ESP32_ADC_REFERENCE_VOLTAGE_MV 1100    
#define HF_ESP32_ADC_MAX_SAMPLING_FREQ 100000     
#define HF_ESP32_ADC_MIN_SAMPLING_FREQ 10         
#define HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ 1000   
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN 256      
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX 4096     
#define HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT 1024 
 
#define HF_ESP32_ADC_ONESHOT_CLK_SRC ADC_RTC_CLK_SRC_DEFAULT    
#define HF_ESP32_ADC_CONTINUOUS_CLK_SRC ADC_DIGI_CLK_SRC_DEFAULT 
#define HF_ESP32_ADC_ULP_MODE ADC_ULP_MODE_DISABLE               
 
// Default fallback (should not be reached)
#else
#error "Unsupported ESP32 variant! Please add support for this ESP32 variant in EspAdc.h"
#endif
 
class EspAdc : public BaseAdc {
public:
  //==============================================//
  // CONSTRUCTION AND INITIALIZATION
  //==============================================//
 
  explicit EspAdc(const hf_adc_unit_config_t& config) noexcept;
 
  ~EspAdc() noexcept override;
 
  // Disable copy and move operations
  // Copy operations are disabled because EspAdc manages hardware resources
  EspAdc(const EspAdc&) = delete;
  EspAdc& operator=(const EspAdc&) = delete;
 
  // Move operations are disabled because EspAdc manages ESP-IDF handles,
  // mutexes, and callback state that are tightly coupled to hardware
  EspAdc(EspAdc&& other) = delete;
  EspAdc& operator=(EspAdc&& other) = delete;
 
  //==============================================//
  // HARDWARE LIMITS (VARIANT-SPECIFIC)
  //==============================================//
 
  // ESP32 ADC Hardware Limits (configured per variant)
  static constexpr hf_u8_t HF_ADC_MAX_UNITS =
      HF_ESP32_ADC_MAX_UNITS; 
  static constexpr hf_u8_t HF_ADC_MAX_CHANNELS =
      HF_ESP32_ADC_MAX_CHANNELS; 
  static constexpr hf_u8_t HF_ADC_MAX_FILTERS =
      HF_ESP32_ADC_MAX_FILTERS; 
  static constexpr hf_u8_t HF_ADC_MAX_MONITORS =
      HF_ESP32_ADC_MAX_MONITORS; 
  static constexpr hf_u16_t HF_ADC_MAX_RAW_VALUE_12BIT =
      HF_ESP32_ADC_MAX_RAW_VALUE; 
  static constexpr hf_u32_t HF_ADC_REFERENCE_VOLTAGE_MV =
      HF_ESP32_ADC_REFERENCE_VOLTAGE_MV; 
  static constexpr hf_u32_t HF_ADC_MAX_SAMPLING_FREQ =
      HF_ESP32_ADC_MAX_SAMPLING_FREQ; 
  static constexpr hf_u32_t HF_ADC_MIN_SAMPLING_FREQ =
      HF_ESP32_ADC_MIN_SAMPLING_FREQ; 
  static constexpr hf_u32_t HF_ADC_DEFAULT_SAMPLING_FREQ =
      HF_ESP32_ADC_DEFAULT_SAMPLING_FREQ; 
  static constexpr size_t HF_ADC_DMA_BUFFER_SIZE_MIN =
      HF_ESP32_ADC_DMA_BUFFER_SIZE_MIN; 
  static constexpr size_t HF_ADC_DMA_BUFFER_SIZE_MAX =
      HF_ESP32_ADC_DMA_BUFFER_SIZE_MAX; 
  static constexpr size_t HF_ADC_DMA_BUFFER_SIZE_DEFAULT =
      HF_ESP32_ADC_DMA_BUFFER_SIZE_DEFAULT; 
 
  static constexpr adc_oneshot_clk_src_t HF_ADC_ONESHOT_CLK_SRC =
      HF_ESP32_ADC_ONESHOT_CLK_SRC; 
  static constexpr adc_continuous_clk_src_t HF_ADC_CONTINUOUS_CLK_SRC =
      HF_ESP32_ADC_CONTINUOUS_CLK_SRC; 
  static constexpr adc_ulp_mode_t HF_ADC_ULP_MODE =
      HF_ESP32_ADC_ULP_MODE; 
 
  //==============================================//
  // BASE CLASS IMPLEMENTATION (REQUIRED)
  //==============================================//
 
  hf_bool_t Initialize() noexcept override;
 
  hf_bool_t Deinitialize() noexcept override;
 
  [[nodiscard]] hf_u8_t GetMaxChannels() const noexcept override;
 
  [[nodiscard]] hf_bool_t IsChannelAvailable(hf_channel_id_t channel_id) const noexcept override;
 
  hf_adc_err_t ReadChannelV(hf_channel_id_t channel_id, float& channel_reading_v,
                            hf_u8_t numOfSamplesToAvg = 1,
                            hf_time_t timeBetweenSamples = 0) noexcept override;
 
  hf_adc_err_t ReadChannelCount(hf_channel_id_t channel_id, hf_u32_t& channel_reading_count,
                                hf_u8_t numOfSamplesToAvg = 1,
                                hf_time_t timeBetweenSamples = 0) noexcept override;
 
  hf_adc_err_t ReadChannel(hf_channel_id_t channel_id, hf_u32_t& channel_reading_count,
                           float& channel_reading_v, hf_u8_t numOfSamplesToAvg = 1,
                           hf_time_t timeBetweenSamples = 0) noexcept override;
 
  hf_adc_err_t ReadMultipleChannels(const hf_channel_id_t* channel_ids, hf_u8_t num_channels,
                                    hf_u32_t* readings, float* voltages) noexcept override;
 
  //==============================================//
  // MODE AND CONFIGURATION OPERATIONS
  //==============================================//
 
  hf_adc_err_t SetMode(hf_adc_mode_t mode) noexcept;
 
  [[nodiscard]] hf_adc_mode_t GetMode() const noexcept;
 
  hf_adc_err_t ConfigureChannel(
      hf_channel_id_t channel_id, hf_adc_atten_t attenuation,
      hf_adc_bitwidth_t bitwidth = hf_adc_bitwidth_t::WIDTH_DEFAULT) noexcept;
 
  hf_adc_err_t SetChannelEnabled(hf_channel_id_t channel_id, hf_bool_t enabled) noexcept;
 
  hf_adc_err_t EnableChannel(hf_channel_id_t channel_id) noexcept;
 
  hf_adc_err_t DisableChannel(hf_channel_id_t channel_id) noexcept;
 
  hf_adc_err_t ReadSingleRaw(hf_channel_id_t channel_id, hf_u32_t& raw_value) noexcept;
 
  hf_adc_err_t ReadSingleVoltage(hf_channel_id_t channel_id, hf_u32_t& voltage_mv) noexcept;
 
  hf_adc_err_t ReadMultipleRaw(const hf_channel_id_t* channel_ids, hf_u8_t num_channels,
                               hf_u32_t* raw_values) noexcept;
 
  hf_adc_err_t ReadMultipleVoltage(const hf_channel_id_t* channel_ids, hf_u8_t num_channels,
                                   hf_u32_t* voltage_values) noexcept;
 
  hf_adc_err_t ReadAveraged(hf_channel_id_t channel_id, hf_u16_t num_samples,
                            hf_u32_t& averaged_value) noexcept;
 
  [[nodiscard]] hf_bool_t IsChannelEnabled(hf_channel_id_t channel_id) const noexcept;
 
  //==============================================//
  // CONTINUOUS MODE OPERATIONS
  //==============================================//
 
  hf_adc_err_t ConfigureContinuous(const hf_adc_continuous_config_t& config) noexcept;
 
  hf_adc_err_t SetContinuousCallback(hf_adc_continuous_callback_t callback,
                                     void* user_data = nullptr) noexcept;
 
  hf_adc_err_t StartContinuous() noexcept;
 
  hf_adc_err_t StopContinuous() noexcept;
 
  [[nodiscard]] hf_bool_t IsContinuousRunning() const noexcept;
 
  hf_adc_err_t ReadContinuousData(hf_u8_t* buffer, hf_u32_t buffer_size, hf_u32_t& bytes_read,
                                  hf_time_t timeout_ms) noexcept;
 
  //==============================================//
  // CALIBRATION OPERATIONS
  //==============================================//
 
  hf_adc_err_t InitializeCalibration(
      hf_adc_atten_t attenuation,
      hf_adc_bitwidth_t bitwidth = hf_adc_bitwidth_t::WIDTH_DEFAULT) noexcept;
 
  [[nodiscard]] hf_bool_t IsCalibrationAvailable(hf_adc_atten_t attenuation) const noexcept;
 
  hf_adc_err_t RawToVoltage(hf_u32_t raw_count, hf_adc_atten_t attenuation,
                            hf_u32_t& voltage_mv) noexcept;
 
  //==============================================//
  // FILTER OPERATIONS
  //==============================================//
 
  hf_adc_err_t ConfigureFilter(const hf_adc_filter_config_t& filter_config) noexcept;
 
  hf_adc_err_t SetFilterEnabled(hf_u8_t filter_id, hf_bool_t enabled) noexcept;
 
  //==============================================//
  // MONITOR OPERATIONS
  //==============================================//
 
  hf_adc_err_t ConfigureMonitor(const hf_adc_monitor_config_t& monitor_config) noexcept;
 
  hf_adc_err_t SetMonitorCallback(hf_u8_t monitor_id, hf_adc_monitor_callback_t callback,
                                  void* user_data = nullptr) noexcept;
 
  hf_adc_err_t SetMonitorEnabled(hf_u8_t monitor_id, hf_bool_t enabled) noexcept;
 
  //==============================================//
  // DIAGNOSTICS AND STATISTICS
  //==============================================//
 
  hf_adc_err_t GetStatistics(hf_adc_statistics_t& statistics) noexcept override;
 
  hf_adc_err_t GetDiagnostics(hf_adc_diagnostics_t& diagnostics) noexcept override;
 
  hf_adc_err_t ResetStatistics() noexcept override;
 
  [[nodiscard]] hf_adc_err_t GetLastError() const noexcept;
 
  [[nodiscard]] const hf_adc_unit_config_t& GetUnitConfig() const noexcept;
 
private:
  //==============================================//
  // PRIVATE IMPLEMENTATION
  //==============================================//
 
  // Forward declarations and internal structures
  struct MonitorContext {
    uint8_t monitor_id;                 
    hf_channel_id_t channel_id;         
    uint32_t high_threshold;            
    uint32_t low_threshold;             
    hf_adc_monitor_callback_t callback; 
    void* user_data;                    
    EspAdc* adc_instance;               
  };
 
  // Internal helper methods
  hf_adc_err_t InitializeOneshot() noexcept;
  hf_adc_err_t InitializeContinuous() noexcept;
  hf_adc_err_t DeinitializeOneshot() noexcept;
  hf_adc_err_t DeinitializeContinuous() noexcept;
  hf_adc_err_t ReadOneshotRaw(hf_channel_id_t channel_id, hf_u32_t& raw_value) noexcept;
  hf_adc_err_t ValidateChannelId(hf_channel_id_t channel_id) const noexcept;
  hf_adc_err_t ValidateConfiguration() const noexcept;
  hf_adc_err_t UpdateStatistics(hf_adc_err_t result, uint64_t start_time_us) noexcept;
  uint64_t GetCurrentTimeUs() const noexcept;
  void UpdateDiagnostics(hf_adc_err_t error) noexcept;
 
  // Static callback functions for ESP-IDF
  static hf_bool_t IRAM_ATTR ContinuousCallback(adc_continuous_handle_t handle,
                                                const adc_continuous_evt_data_t* edata,
                                                void* user_data) noexcept;
  static hf_bool_t IRAM_ATTR HighThresholdCallback(adc_monitor_handle_t monitor_handle,
                                                   const adc_monitor_evt_data_t* event_data,
                                                   void* user_data) noexcept;
  static hf_bool_t IRAM_ATTR LowThresholdCallback(adc_monitor_handle_t monitor_handle,
                                                  const adc_monitor_evt_data_t* event_data,
                                                  void* user_data) noexcept;
 
  //==============================================//
  // MEMBER VARIABLES
  //==============================================//
 
  // Configuration and state
  hf_adc_unit_config_t config_;               
  std::atomic<hf_bool_t> continuous_running_; 
  std::atomic<hf_adc_err_t> last_error_;      
 
  // Thread safety
  mutable PlatformMutex config_mutex_; 
  mutable PlatformMutex stats_mutex_;  
 
  // ESP-IDF handles
  adc_oneshot_unit_handle_t oneshot_handle_;  
  adc_continuous_handle_t continuous_handle_; 
  std::array<adc_cali_handle_t, 4>
      calibration_handles_; 
  std::array<adc_iir_filter_handle_t, HF_ADC_MAX_FILTERS> filter_handles_; 
  std::array<adc_monitor_handle_t, HF_ADC_MAX_MONITORS> monitor_handles_;  
 
  // Callback data
  hf_adc_continuous_callback_t continuous_callback_; 
  void* continuous_user_data_;                       
  std::array<hf_adc_monitor_callback_t, HF_ADC_MAX_MONITORS>
      monitor_callbacks_;                                            
  std::array<void*, HF_ADC_MAX_MONITORS> monitor_user_data_;         
  std::array<MonitorContext, HF_ADC_MAX_MONITORS> monitor_contexts_; 
 
  // Statistics and diagnostics
  mutable hf_adc_statistics_t statistics_;   
  mutable hf_adc_diagnostics_t diagnostics_; 
};
 
#endif // HF_MCU_FAMILY_ESP32