EspTypes_ADC.h

Go to the documentation of this file.

 
#pragma once
 
#include "BaseAdc.h"
#include "EspTypes_Base.h"
#include "HardwareTypes.h"
#include "McuSelect.h" // Central MCU platform selection (includes all ESP-IDF)
 
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
 
#include <esp_adc/adc_continuous.h>
#include <esp_adc/adc_oneshot.h>
 
#ifdef __cplusplus
}
#endif
 
//==============================================================================
// ESSENTIAL ADC TYPES (ESP32)
//==============================================================================
 
enum class hf_adc_mode_t : uint8_t {
  ONESHOT = 0,   
  CONTINUOUS = 1 
};
 
enum class hf_adc_atten_t : uint8_t {
  ATTEN_DB_0 = ADC_ATTEN_DB_0,     
  ATTEN_DB_2_5 = ADC_ATTEN_DB_2_5, 
  ATTEN_DB_6 = ADC_ATTEN_DB_6,     
  ATTEN_DB_12 = ADC_ATTEN_DB_12    
};
 
enum class hf_adc_bitwidth_t : uint8_t {
  WIDTH_9BIT = ADC_BITWIDTH_9,         
  WIDTH_10BIT = ADC_BITWIDTH_10,       
  WIDTH_11BIT = ADC_BITWIDTH_11,       
  WIDTH_12BIT = ADC_BITWIDTH_12,       
  WIDTH_13BIT = ADC_BITWIDTH_13,       
  WIDTH_DEFAULT = ADC_BITWIDTH_DEFAULT 
};
 
enum class hf_adc_filter_coeff_t : uint8_t {
  COEFF_2 = 0,  
  COEFF_4 = 1,  
  COEFF_8 = 2,  
  COEFF_16 = 3, 
  COEFF_64 = 4  
};
 
enum class hf_adc_monitor_event_type_t : uint8_t {
  HIGH_THRESH = 0, 
  LOW_THRESH = 1   
};
 
struct hf_adc_channel_config_t {
  hf_channel_id_t channel_id; 
  hf_adc_atten_t attenuation; 
  hf_adc_bitwidth_t bitwidth; 
  bool enabled;               
 
  hf_adc_channel_config_t()
      : channel_id(0), attenuation(hf_adc_atten_t::ATTEN_DB_12),
        bitwidth(hf_adc_bitwidth_t::WIDTH_DEFAULT), enabled(false) {}
};
 
struct hf_adc_continuous_config_t {
  uint32_t sample_freq_hz; 
  uint32_t
      samples_per_frame; 
  uint32_t max_store_frames; 
  bool flush_pool;           
 
  hf_adc_continuous_config_t()
      : sample_freq_hz(1000), samples_per_frame(64), max_store_frames(4), flush_pool(false) {}
};
 
struct hf_adc_filter_config_t {
  uint8_t filter_id;                 
  hf_channel_id_t channel_id;        
  hf_adc_filter_coeff_t coefficient; 
 
  hf_adc_filter_config_t()
      : filter_id(0), channel_id(0), coefficient(hf_adc_filter_coeff_t::COEFF_4) {}
};
 
struct hf_adc_monitor_config_t {
  uint8_t monitor_id;         
  hf_channel_id_t channel_id; 
  uint32_t high_threshold;    
  uint32_t low_threshold;     
 
  hf_adc_monitor_config_t()
      : monitor_id(0), channel_id(0), high_threshold(3000), low_threshold(1000) {}
};
 
struct hf_adc_calibration_config_t {
  bool enable_calibration;          
  bool auto_calibration;            
  uint32_t calibration_interval_ms; 
 
  hf_adc_calibration_config_t()
      : enable_calibration(true), auto_calibration(true), calibration_interval_ms(60000) {}
};
 
struct hf_adc_unit_config_t {
  uint8_t unit_id;                                
  hf_adc_mode_t mode;                             
  hf_adc_bitwidth_t bit_width;                    
  hf_adc_channel_config_t channel_configs[7];     
  hf_adc_continuous_config_t continuous_config;   
  hf_adc_calibration_config_t calibration_config; 
 
  hf_adc_unit_config_t()
      : unit_id(1), mode(hf_adc_mode_t::ONESHOT), bit_width(hf_adc_bitwidth_t::WIDTH_DEFAULT) {}
};
 
struct hf_adc_continuous_data_t {
  uint8_t* buffer;           
  uint32_t size;             
  uint32_t conversion_count; 
  uint64_t timestamp_us;     
 
  hf_adc_continuous_data_t() : buffer(nullptr), size(0), conversion_count(0), timestamp_us(0) {}
};
 
struct hf_adc_monitor_event_t {
  uint8_t monitor_id;                     
  hf_channel_id_t channel_id;             
  uint32_t raw_value;                     
  hf_adc_monitor_event_type_t event_type; 
  uint64_t timestamp_us;                  
 
  hf_adc_monitor_event_t()
      : monitor_id(0), channel_id(0), raw_value(0),
        event_type(hf_adc_monitor_event_type_t::HIGH_THRESH), timestamp_us(0) {}
};
 
//==============================================================================
// CALLBACK TYPE DEFINITIONS
//==============================================================================
 
using hf_adc_continuous_callback_t = bool (*)(const hf_adc_continuous_data_t* data,
                                              void* user_data);
 
using hf_adc_monitor_callback_t = void (*)(const hf_adc_monitor_event_t* event, void* user_data);
 
//==============================================================================
// ESP32 ADC CONSTANTS
//==============================================================================
 
constexpr uint32_t HF_ESP32_ADC_DATA_BYTES_PER_CONV =
    SOC_ADC_DIGI_DATA_BYTES_PER_CONV;                  
constexpr uint32_t HF_ESP32_ADC_MIN_FRAME_SIZE = 64;   
constexpr uint32_t HF_ESP32_ADC_MAX_FRAME_SIZE = 1024; 
constexpr uint32_t HF_ESP32_ADC_DEFAULT_FRAME_SIZE = 256; 
 
inline constexpr uint32_t CalcFrameSize(uint32_t samples_per_frame,
                                        uint32_t enabled_channels) noexcept {
  return samples_per_frame * enabled_channels * HF_ESP32_ADC_DATA_BYTES_PER_CONV;
}
 
inline constexpr uint32_t CalcBufferPoolSize(uint32_t samples_per_frame, uint32_t enabled_channels,
                                             uint32_t max_store_frames) noexcept {
  return CalcFrameSize(samples_per_frame, enabled_channels) * max_store_frames;
}
 
inline constexpr bool IsValidContinuousConfig(uint32_t samples_per_frame, uint32_t enabled_channels,
                                              uint32_t max_store_frames) noexcept {
  if (enabled_channels == 0 || samples_per_frame == 0 || max_store_frames == 0) {
    return false;
  }
 
  uint32_t frame_size = CalcFrameSize(samples_per_frame, enabled_channels);
  uint32_t pool_size = CalcBufferPoolSize(samples_per_frame, enabled_channels, max_store_frames);
 
  return (frame_size >= HF_ESP32_ADC_MIN_FRAME_SIZE) &&
         (frame_size <= HF_ESP32_ADC_MAX_FRAME_SIZE) &&
         (pool_size <= 32768) && // Reasonable max pool size (32KB)
         ((frame_size % HF_ESP32_ADC_DATA_BYTES_PER_CONV) == 0);
}
 
inline constexpr bool IsValidFrameSize(uint32_t frame_size) noexcept {
  return (frame_size >= HF_ESP32_ADC_MIN_FRAME_SIZE) &&
         (frame_size <= HF_ESP32_ADC_MAX_FRAME_SIZE) &&
         ((frame_size % HF_ESP32_ADC_DATA_BYTES_PER_CONV) == 0);
}
 
inline constexpr uint32_t GetFrameResultCount(uint32_t frame_size) noexcept {
  return frame_size / HF_ESP32_ADC_DATA_BYTES_PER_CONV;
}
 
//==============================================================================
// COMMON ADC UTILITY FUNCTIONS
//==============================================================================
 
inline constexpr hf_channel_id_t GpioToAdcChannel(hf_pin_num_t gpio_pin) noexcept {
  // Note: This is a simplified compile-time function.
  // For accurate GPIO-to-channel conversion, use adc_continuous_io_to_channel()
  // at runtime, which handles all ESP32 variants correctly.
  return (gpio_pin >= 0 && gpio_pin <= 6) ? static_cast<hf_channel_id_t>(gpio_pin)
                                          : HF_INVALID_CHANNEL;
}
 
inline constexpr hf_pin_num_t AdcChannelToGpio(hf_channel_id_t channel_id) noexcept {
  // Note: This is a simplified compile-time function.
  // For accurate channel-to-GPIO conversion, use adc_continuous_channel_to_io()
  // at runtime, which handles all ESP32 variants correctly.
  return (channel_id <= 6) ? static_cast<hf_pin_num_t>(channel_id) : HF_INVALID_PIN;
}
 
inline constexpr uint32_t GetMaxInputVoltage(hf_adc_atten_t atten) noexcept {
  switch (atten) {
  case hf_adc_atten_t::ATTEN_DB_0:
    return 950; // ~0.95V
  case hf_adc_atten_t::ATTEN_DB_2_5:
    return 1320; // ~1.32V
  case hf_adc_atten_t::ATTEN_DB_6:
    return 1980; // ~1.98V
  case hf_adc_atten_t::ATTEN_DB_12:
    return 3300; // ~3.3V
  default:
    return 0;
  }
}
 
inline constexpr uint32_t GetMaxRawValue(hf_adc_bitwidth_t bitwidth) noexcept {
  switch (bitwidth) {
  case hf_adc_bitwidth_t::WIDTH_9BIT:
    return 511; // 2^9 - 1
  case hf_adc_bitwidth_t::WIDTH_10BIT:
    return 1023; // 2^10 - 1
  case hf_adc_bitwidth_t::WIDTH_11BIT:
    return 2047; // 2^11 - 1
  case hf_adc_bitwidth_t::WIDTH_12BIT:
    return 4095; // 2^12 - 1
  default:
    return 4095;
  }
}
 
//==============================================================================
// END OF ESPADC TYPES - MINIMAL AND ESSENTIAL ONLY
//==============================================================================