NtcTemperatureHandler.h

Go to the documentation of this file.

 
#pragma once
 
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseTemperature.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseAdc.h"
#include "core/hf-core-drivers/external/hf-ntc-thermistor-driver/inc/ntc_thermistor.hpp"
#include "RtosMutex.h"
#include "handlers/common/HandlerCommon.h"
#include "core/hf-core-utils/hf-utils-rtos-wrap/include/PeriodicTimer.h"
 
#include <memory>
#include <cfloat>
#include <array>
 
//--------------------------------------
//  NTC ADC Adapter (BaseAdc → ntc::AdcInterface bridge)
//--------------------------------------
 
class NtcAdcAdapter : public ntc::AdcInterface<NtcAdcAdapter> {
public:
    explicit NtcAdcAdapter(BaseAdc* adc, float ref_voltage = 3.3f, uint8_t res_bits = 12) noexcept
        : adc_(adc), reference_voltage_(ref_voltage), resolution_bits_(res_bits) {}
 
    [[nodiscard]] bool IsInitialized() const { return adc_ != nullptr && adc_->IsInitialized(); }
    bool EnsureInitialized() { return adc_ != nullptr && adc_->EnsureInitialized(); }
    [[nodiscard]] bool IsChannelAvailable(uint8_t channel) const {
        return adc_ != nullptr && adc_->IsChannelAvailable(static_cast<hf_channel_id_t>(channel));
    }
    ntc::AdcError ReadChannelCount(uint8_t channel, uint32_t* count) {
        if (adc_ == nullptr || count == nullptr) return ntc::AdcError::ReadFailed;
        hf_u32_t raw = 0;
        auto err = adc_->ReadChannelCount(static_cast<hf_channel_id_t>(channel), raw);
        if (err != hf_adc_err_t::ADC_SUCCESS) return ntc::AdcError::ReadFailed;
        *count = raw;
        return ntc::AdcError::Success;
    }
    ntc::AdcError ReadChannelV(uint8_t channel, float* voltage_v) {
        if (adc_ == nullptr || voltage_v == nullptr) return ntc::AdcError::ReadFailed;
        float v = 0.0f;
        auto err = adc_->ReadChannelV(static_cast<hf_channel_id_t>(channel), v);
        if (err != hf_adc_err_t::ADC_SUCCESS) return ntc::AdcError::ReadFailed;
        *voltage_v = v;
        return ntc::AdcError::Success;
    }
    [[nodiscard]] float GetReferenceVoltage() const { return reference_voltage_; }
    [[nodiscard]] uint8_t GetResolutionBits() const { return resolution_bits_; }
    void DelayMs(uint32_t ms) { handler_utils::DelayMs(ms); }
 
private:
    BaseAdc* adc_;
    float reference_voltage_;
    uint8_t resolution_bits_;
};
 
using NtcThermistorConcrete = NtcThermistor<NtcAdcAdapter>;
 
//--------------------------------------
//  NTC Temperature Handler Configuration
//--------------------------------------
 
typedef struct {
    NtcType ntc_type;                       
    uint8_t adc_channel;                    
    float voltage_divider_series_resistance; 
    float voltage_divider_parallel_resistance; 
    float reference_voltage;                
    float calibration_offset;               
    float beta_value;                       
    NtcConversionMethod conversion_method;  
    uint32_t sample_count;                  
    uint32_t sample_delay_ms;               
    float min_temperature;                  
    float max_temperature;                  
    bool enable_filtering;                  
    float filter_alpha;                     
    bool enable_threshold_monitoring;       
    float low_threshold_celsius;            
    float high_threshold_celsius;           
    hf_temp_threshold_callback_t threshold_callback; 
    void* threshold_user_data;              
    const char* sensor_name;                
    const char* sensor_description;         
} ntc_temp_handler_config_t;
 
#define NTC_TEMP_HANDLER_CONFIG_DEFAULT() { \
    .ntc_type = NtcType::NtcG163Jft103Ft1S, \
    .adc_channel = 0, \
    .voltage_divider_series_resistance = 10000.0f, \
    .voltage_divider_parallel_resistance = 0.0f, \
    .reference_voltage = 3.3f, \
    .calibration_offset = 0.0f, \
    .beta_value = 0.0f, \
    .conversion_method = NtcConversionMethod::Auto, \
    .sample_count = 1, \
    .sample_delay_ms = 0, \
    .min_temperature = -40.0f, \
    .max_temperature = 125.0f, \
    .enable_filtering = false, \
    .filter_alpha = 0.1f, \
    .enable_threshold_monitoring = false, \
    .low_threshold_celsius = -40.0f, \
    .high_threshold_celsius = 125.0f, \
    .threshold_callback = nullptr, \
    .threshold_user_data = nullptr, \
    .sensor_name = "NTC_Temperature_Sensor", \
    .sensor_description = "NTC Thermistor Temperature Sensor" \
}
 
//--------------------------------------
//  NtcTemperatureHandler Class
//--------------------------------------
 
class NtcTemperatureHandler : public BaseTemperature {
public:
    //==============================================================//
    // CONSTRUCTORS AND DESTRUCTOR
    //==============================================================//
    
    NtcTemperatureHandler(NtcType ntc_type, BaseAdc* adc_interface, const char* sensor_name = nullptr) noexcept;
    
    NtcTemperatureHandler(BaseAdc* adc_interface, const ntc_temp_handler_config_t& config) noexcept;
    
    NtcTemperatureHandler(const NtcTemperatureHandler&) = delete;
    
    NtcTemperatureHandler& operator=(const NtcTemperatureHandler&) = delete;
    
    NtcTemperatureHandler(NtcTemperatureHandler&&) = delete;
    NtcTemperatureHandler& operator=(NtcTemperatureHandler&&) = delete;
    
    virtual ~NtcTemperatureHandler() noexcept;
    
    //==============================================================//
    // BASE TEMPERATURE INTERFACE IMPLEMENTATION
    //==============================================================//
    
    // Pure virtual implementations
    bool Initialize() noexcept override;
    bool Deinitialize() noexcept override;
    hf_temp_err_t ReadTemperatureCelsiusImpl(float* temperature_celsius) noexcept override;
    
    // Information interface
    hf_temp_err_t GetSensorInfo(hf_temp_sensor_info_t* info) const noexcept override;
    hf_u32_t GetCapabilities() const noexcept override;
    
    // Advanced features (supported)
    hf_temp_err_t SetRange(float min_celsius, float max_celsius) noexcept override;
    hf_temp_err_t GetRange(float* min_celsius, float* max_celsius) const noexcept override;
    hf_temp_err_t GetResolution(float* resolution_celsius) const noexcept override;
    hf_temp_err_t SetThresholds(float low_threshold_celsius, float high_threshold_celsius) noexcept override;
    hf_temp_err_t GetThresholds(float* low_threshold_celsius, float* high_threshold_celsius) const noexcept override;
    hf_temp_err_t EnableThresholdMonitoring(hf_temp_threshold_callback_t callback, void* user_data) noexcept override;
    hf_temp_err_t DisableThresholdMonitoring() noexcept override;
    hf_temp_err_t StartContinuousMonitoring(hf_u32_t sample_rate_hz, hf_temp_reading_callback_t callback, void* user_data) noexcept override;
    hf_temp_err_t StopContinuousMonitoring() noexcept override;
    bool IsMonitoringActive() const noexcept override;
    hf_temp_err_t SetCalibrationOffset(float offset_celsius) noexcept override;
    hf_temp_err_t GetCalibrationOffset(float* offset_celsius) const noexcept override;
    hf_temp_err_t ResetCalibration() noexcept override;
    hf_temp_err_t EnterSleepMode() noexcept override;
    hf_temp_err_t ExitSleepMode() noexcept override;
    bool IsSleeping() const noexcept override;
    hf_temp_err_t SelfTest() noexcept override;
    hf_temp_err_t CheckHealth() noexcept override;
    hf_temp_err_t GetStatistics(hf_temp_statistics_t& statistics) noexcept override;
    hf_temp_err_t GetDiagnostics(hf_temp_diagnostics_t& diagnostics) noexcept override;
    hf_temp_err_t ResetStatistics() noexcept override;
    hf_temp_err_t ResetDiagnostics() noexcept override;
    
    //==============================================================//
    // NTC-SPECIFIC METHODS
    //==============================================================//
    
    void* GetNtcThermistor() noexcept;
    
    const void* GetNtcThermistor() const noexcept;
    
    NtcError GetNtcReading(ntc_reading_t* reading) noexcept;
    
    NtcError GetNtcConfiguration(ntc_config_t* config) const noexcept;
    
    NtcError SetNtcConfiguration(const ntc_config_t& config) noexcept;
    
    NtcError GetResistance(float* resistance_ohms) noexcept;
    
    NtcError GetVoltage(float* voltage_volts) noexcept;
    
    NtcError GetRawAdcValue(uint32_t* adc_value) noexcept;
    
    hf_temp_err_t Calibrate(float reference_temperature_celsius) noexcept override;
    
    NtcError SetConversionMethod(NtcConversionMethod method) noexcept;
    
    NtcError SetVoltageDivider(float series_resistance) noexcept;
    
    NtcError SetReferenceVoltage(float reference_voltage) noexcept;
    
    NtcError SetBetaValue(float beta_value) noexcept;
    
    NtcError SetAdcChannel(uint8_t adc_channel) noexcept;
    
    NtcError SetSamplingParameters(uint32_t sample_count, uint32_t sample_delay_ms) noexcept;
    
    NtcError SetFiltering(bool enable, float alpha = 0.1f) noexcept;
    
    const char* GetSensorName() const noexcept;
    
    const char* GetSensorDescription() const noexcept;
 
    //==============================================================//
    // DIRECT DRIVER ACCESS
    //==============================================================//
 
    [[nodiscard]] NtcThermistorConcrete* GetDriver() noexcept;
    [[nodiscard]] const NtcThermistorConcrete* GetDriver() const noexcept;
 
private:
    //==============================================================//
    // PRIVATE MEMBER VARIABLES
    //==============================================================//
    
    mutable RtosMutex mutex_;              
    std::unique_ptr<NtcAdcAdapter> ntc_adc_adapter_;       
    std::unique_ptr<NtcThermistorConcrete> ntc_thermistor_; 
    BaseAdc* adc_interface_;                
    ntc_temp_handler_config_t config_;      
    
    // BaseTemperature state
    hf_temp_state_t current_state_;         
    hf_temp_config_t base_config_;          
    
    // Threshold monitoring
    float low_threshold_celsius_;           
    float high_threshold_celsius_;          
    hf_temp_threshold_callback_t threshold_callback_; 
    void* threshold_user_data_;             
    
    // Continuous monitoring (using hardware-agnostic PeriodicTimer)
    hf_u32_t sample_rate_hz_;               
    hf_temp_reading_callback_t continuous_callback_; 
    void* continuous_user_data_;            
    PeriodicTimer monitoring_timer_;        
    hf_u32_t monitoring_context_id_;        
    float calibration_offset_;             
    
    // Statistics and diagnostics
    hf_temp_statistics_t statistics_;       
    hf_temp_diagnostics_t diagnostics_;     
    
    // Packed bools (grouped to avoid padding waste)
    bool initialized_;                      
    bool threshold_monitoring_enabled_;     
    bool monitoring_active_;               
    
    //==============================================================//
    // PRIVATE HELPER METHODS
    //==============================================================//
    
    void SetLastError(hf_temp_err_t error) noexcept;
    
    void UpdateStatistics(bool operation_successful, hf_u32_t operation_time_us) noexcept;
    
    void UpdateDiagnostics(hf_temp_err_t error) noexcept;
    
    bool InitializeNtcThermistor() noexcept;
    
    hf_temp_err_t ConvertNtcError(NtcError ntc_error) const noexcept;
    
    void CheckThresholds(float temperature_celsius) noexcept;
    
    static void ContinuousMonitoringCallback(uint32_t arg);
 
    static hf_u32_t RegisterMonitoringContext(NtcTemperatureHandler* handler) noexcept;
    static void UnregisterMonitoringContext(hf_u32_t context_id) noexcept;
    static NtcTemperatureHandler* ResolveMonitoringContext(hf_u32_t context_id) noexcept;
 
    static constexpr hf_u32_t kMonitoringContextSlots = 8;
    static RtosMutex callback_registry_mutex_;
    static std::array<NtcTemperatureHandler*, kMonitoringContextSlots> callback_registry_;
    
    void UpdateBaseDiagnostics(hf_temp_err_t error) noexcept;
    
    hf_temp_err_t ValidateConfiguration(const ntc_temp_handler_config_t& config) const noexcept;
    
    static hf_u64_t GetCurrentTimeUs() noexcept;
};