ValveManager.h

Go to the documentation of this file.

 
#ifndef FLUX_VALVE_MANAGER_H_
#define FLUX_VALVE_MANAGER_H_
 
#include <array>
#include <atomic>
#include <cstdint>
#include <optional>
#include <string_view>
 
#include "RtosMutex.h"
#include "flux_hal/flux_hal_types.hpp"
#include "handlers/max22200/Max22200Handler.h"
#include "handlers/tle92466ed/Tle92466edHandler.h"
 
//==============================================================================
// VALVE ERROR CODES
//==============================================================================
 
enum class hf_valve_err_t : uint8_t {
    // Success
    VALVE_SUCCESS                   = 0,
 
    // General errors
    VALVE_ERR_NOT_INITIALIZED       = 1,
    VALVE_ERR_DRIVER_NOT_AVAILABLE  = 2,
    VALVE_ERR_INVALID_CHANNEL       = 3,
    VALVE_ERR_CHANNEL_TYPE_MISMATCH = 4,
    VALVE_ERR_INVALID_PARAMETER     = 5,
    VALVE_ERR_NULL_POINTER          = 6,
 
    // Communication errors (SPI layer)
    VALVE_ERR_SPI_BUS_ERROR         = 10,
    VALVE_ERR_SPI_TIMEOUT           = 11,
    VALVE_ERR_SPI_TRANSFER_FAILED   = 12,
    VALVE_ERR_SPI_CRC_ERROR         = 13,
    VALVE_ERR_SPI_FRAME_ERROR       = 14,
 
    // Driver-level errors
    VALVE_ERR_HARDWARE_FAULT        = 20,
    VALVE_ERR_DEVICE_NOT_RESPONDING = 21,
    VALVE_ERR_WRONG_DEVICE_ID       = 22,
    VALVE_ERR_REGISTER_ERROR        = 23,
    VALVE_ERR_CONFIGURATION_ERROR   = 24,
    VALVE_ERR_WRONG_MODE            = 25,
    VALVE_ERR_WRITE_TO_READ_ONLY    = 26,
    VALVE_ERR_TIMEOUT               = 27,
 
    // Manager-level errors
    VALVE_ERR_MUTEX_TIMEOUT         = 30,
    VALVE_ERR_DEPENDENCY_NOT_READY  = 31,
 
    // Catch-all
    VALVE_ERR_UNKNOWN               = 255
};
 
constexpr const char* HfValveErrToString(hf_valve_err_t err) noexcept {
    switch (err) {
        case hf_valve_err_t::VALVE_SUCCESS:                   return "Success";
        case hf_valve_err_t::VALVE_ERR_NOT_INITIALIZED:       return "Manager not initialized";
        case hf_valve_err_t::VALVE_ERR_DRIVER_NOT_AVAILABLE:  return "Driver IC not available";
        case hf_valve_err_t::VALVE_ERR_INVALID_CHANNEL:       return "Invalid channel for operation";
        case hf_valve_err_t::VALVE_ERR_CHANNEL_TYPE_MISMATCH: return "Channel type mismatch (sol/prop)";
        case hf_valve_err_t::VALVE_ERR_INVALID_PARAMETER:     return "Invalid parameter value";
        case hf_valve_err_t::VALVE_ERR_NULL_POINTER:          return "Null handler/driver pointer";
        case hf_valve_err_t::VALVE_ERR_SPI_BUS_ERROR:         return "SPI bus communication error";
        case hf_valve_err_t::VALVE_ERR_SPI_TIMEOUT:           return "SPI transfer timeout";
        case hf_valve_err_t::VALVE_ERR_SPI_TRANSFER_FAILED:   return "SPI data transfer failed";
        case hf_valve_err_t::VALVE_ERR_SPI_CRC_ERROR:         return "SPI CRC mismatch";
        case hf_valve_err_t::VALVE_ERR_SPI_FRAME_ERROR:       return "SPI frame error from device";
        case hf_valve_err_t::VALVE_ERR_HARDWARE_FAULT:        return "Hardware fault detected";
        case hf_valve_err_t::VALVE_ERR_DEVICE_NOT_RESPONDING: return "Device not responding";
        case hf_valve_err_t::VALVE_ERR_WRONG_DEVICE_ID:       return "Wrong device ID";
        case hf_valve_err_t::VALVE_ERR_REGISTER_ERROR:        return "Register read/write error";
        case hf_valve_err_t::VALVE_ERR_CONFIGURATION_ERROR:   return "Configuration failed";
        case hf_valve_err_t::VALVE_ERR_WRONG_MODE:            return "Operation not allowed in mode";
        case hf_valve_err_t::VALVE_ERR_WRITE_TO_READ_ONLY:    return "Write to read-only register";
        case hf_valve_err_t::VALVE_ERR_TIMEOUT:               return "Operation timeout";
        case hf_valve_err_t::VALVE_ERR_MUTEX_TIMEOUT:         return "Mutex acquisition timeout";
        case hf_valve_err_t::VALVE_ERR_DEPENDENCY_NOT_READY:  return "Required dependency not ready";
        case hf_valve_err_t::VALVE_ERR_UNKNOWN:               return "Unknown error";
        default:                                              return "Unknown valve error";
    }
}
 
constexpr bool HfValveErrOk(hf_valve_err_t err) noexcept {
    return err == hf_valve_err_t::VALVE_SUCCESS;
}
 
// ─── Driver Error Mappings ──────────────────────────────────────────────────
 
constexpr hf_valve_err_t TleDriverErrorToValveError(tle92466ed::DriverError e) noexcept {
    switch (e) {
        case tle92466ed::DriverError::None:              return hf_valve_err_t::VALVE_SUCCESS;
        case tle92466ed::DriverError::NotInitialized:    return hf_valve_err_t::VALVE_ERR_NOT_INITIALIZED;
        case tle92466ed::DriverError::HardwareError:     return hf_valve_err_t::VALVE_ERR_HARDWARE_FAULT;
        case tle92466ed::DriverError::InvalidChannel:    return hf_valve_err_t::VALVE_ERR_INVALID_CHANNEL;
        case tle92466ed::DriverError::InvalidParameter:  return hf_valve_err_t::VALVE_ERR_INVALID_PARAMETER;
        case tle92466ed::DriverError::DeviceNotResponding: return hf_valve_err_t::VALVE_ERR_DEVICE_NOT_RESPONDING;
        case tle92466ed::DriverError::WrongDeviceID:     return hf_valve_err_t::VALVE_ERR_WRONG_DEVICE_ID;
        case tle92466ed::DriverError::RegisterError:     return hf_valve_err_t::VALVE_ERR_REGISTER_ERROR;
        case tle92466ed::DriverError::CRCError:          return hf_valve_err_t::VALVE_ERR_SPI_CRC_ERROR;
        case tle92466ed::DriverError::FaultDetected:     return hf_valve_err_t::VALVE_ERR_HARDWARE_FAULT;
        case tle92466ed::DriverError::ConfigurationError: return hf_valve_err_t::VALVE_ERR_CONFIGURATION_ERROR;
        case tle92466ed::DriverError::TimeoutError:      return hf_valve_err_t::VALVE_ERR_TIMEOUT;
        case tle92466ed::DriverError::WrongMode:         return hf_valve_err_t::VALVE_ERR_WRONG_MODE;
        case tle92466ed::DriverError::SPIFrameError:     return hf_valve_err_t::VALVE_ERR_SPI_FRAME_ERROR;
        case tle92466ed::DriverError::WriteToReadOnly:   return hf_valve_err_t::VALVE_ERR_WRITE_TO_READ_ONLY;
        default:                                         return hf_valve_err_t::VALVE_ERR_UNKNOWN;
    }
}
 
constexpr hf_valve_err_t MaxDriverStatusToValveError(max22200::DriverStatus s) noexcept {
    switch (s) {
        case max22200::DriverStatus::OK:                  return hf_valve_err_t::VALVE_SUCCESS;
        case max22200::DriverStatus::INITIALIZATION_ERROR: return hf_valve_err_t::VALVE_ERR_NOT_INITIALIZED;
        case max22200::DriverStatus::COMMUNICATION_ERROR: return hf_valve_err_t::VALVE_ERR_SPI_BUS_ERROR;
        case max22200::DriverStatus::INVALID_PARAMETER:   return hf_valve_err_t::VALVE_ERR_INVALID_PARAMETER;
        case max22200::DriverStatus::HARDWARE_FAULT:      return hf_valve_err_t::VALVE_ERR_HARDWARE_FAULT;
        case max22200::DriverStatus::TIMEOUT:             return hf_valve_err_t::VALVE_ERR_TIMEOUT;
        default:                                          return hf_valve_err_t::VALVE_ERR_UNKNOWN;
    }
}
 
//==============================================================================
// VALVE CHANNEL IDENTIFIERS
//==============================================================================
 
enum class ValveDriverType : uint8_t {
    MAX22200  = 0,  
    TLE92466  = 1,  
    UNKNOWN   = 0xFF
};
 
enum class ValveChannel : uint8_t {
    // MAX22200 channels (0-7)
    SOL_CH0 = 0,   SOL_CH1 = 1,   SOL_CH2 = 2,   SOL_CH3 = 3,
    SOL_CH4 = 4,   SOL_CH5 = 5,   SOL_CH6 = 6,   SOL_CH7 = 7,
 
    // TLE92466ED channels (8-13)
    PROP_CH0 = 8,  PROP_CH1 = 9,  PROP_CH2 = 10,
    PROP_CH3 = 11, PROP_CH4 = 12, PROP_CH5 = 13,
 
    CHANNEL_COUNT = 14
};
 
struct ValveChannelInfo {
    ValveChannel channel;           
    ValveDriverType driver_type;    
    uint8_t hw_channel;             
    std::string_view name;          
};
 
static constexpr ValveChannelInfo kValveChannelMap[] = {
    { ValveChannel::SOL_CH0,  ValveDriverType::MAX22200, 0, "SOL_CH0"  },
    { ValveChannel::SOL_CH1,  ValveDriverType::MAX22200, 1, "SOL_CH1"  },
    { ValveChannel::SOL_CH2,  ValveDriverType::MAX22200, 2, "SOL_CH2"  },
    { ValveChannel::SOL_CH3,  ValveDriverType::MAX22200, 3, "SOL_CH3"  },
    { ValveChannel::SOL_CH4,  ValveDriverType::MAX22200, 4, "SOL_CH4"  },
    { ValveChannel::SOL_CH5,  ValveDriverType::MAX22200, 5, "SOL_CH5"  },
    { ValveChannel::SOL_CH6,  ValveDriverType::MAX22200, 6, "SOL_CH6"  },
    { ValveChannel::SOL_CH7,  ValveDriverType::MAX22200, 7, "SOL_CH7"  },
    { ValveChannel::PROP_CH0, ValveDriverType::TLE92466, 0, "PROP_CH0" },
    { ValveChannel::PROP_CH1, ValveDriverType::TLE92466, 1, "PROP_CH1" },
    { ValveChannel::PROP_CH2, ValveDriverType::TLE92466, 2, "PROP_CH2" },
    { ValveChannel::PROP_CH3, ValveDriverType::TLE92466, 3, "PROP_CH3" },
    { ValveChannel::PROP_CH4, ValveDriverType::TLE92466, 4, "PROP_CH4" },
    { ValveChannel::PROP_CH5, ValveDriverType::TLE92466, 5, "PROP_CH5" },
};
 
static constexpr size_t kValveChannelCount = sizeof(kValveChannelMap) / sizeof(kValveChannelMap[0]);
 
//==============================================================================
// VALVE STATUS STRUCTURES
//==============================================================================
 
struct ValveChannelState {
    bool enabled{false};            
    bool configured{false};         
    uint16_t current_ma{0};         
    float duty_percent{0.0f};       
    float pwm_frequency_hz{0.0f};   
    float dither_amplitude_ma{0.0f};
    float dither_frequency_hz{0.0f};
    uint32_t activation_count{0};   
    uint32_t error_count{0};        
};
 
struct ValveSystemDiagnostics {
    bool system_healthy;            
    bool max22200_initialized;      
    bool tle92466_initialized;      
    uint8_t total_channels;         
    uint8_t configured_channels;    
    uint8_t active_channels;        
    uint32_t total_activations;     
    uint32_t total_errors;          
};
 
//==============================================================================
// VALVE MANAGER
//==============================================================================
 
class ValveManager {
public:
    //==========================================================================
    // SINGLETON
    //==========================================================================
 
    static ValveManager& GetInstance() noexcept;
 
    ValveManager(const ValveManager&) = delete;
    ValveManager& operator=(const ValveManager&) = delete;
    ValveManager(ValveManager&&) = delete;
    ValveManager& operator=(ValveManager&&) = delete;
 
    //==========================================================================
    // INITIALIZATION
    //==========================================================================
 
    [[nodiscard]] bool EnsureInitialized() noexcept;
 
    [[nodiscard]] bool IsInitialized() const noexcept { return initialized_.load(std::memory_order_acquire); }
 
    [[nodiscard]] bool IsBankReady(ValveDriverType bank) const noexcept;
 
    [[nodiscard]] flux::hal::ManagerError GetManagerError() const noexcept {
        return manager_error_.load(std::memory_order_acquire);
    }
 
    bool Deinitialize() noexcept;
 
    //==========================================================================
    // HARDWARE ENABLE PATH (SafeHold) — no SPI, no mutex
    //==========================================================================
 
    bool DropEnablePins() noexcept;
 
    bool RearmEnablePins() noexcept;
 
    [[nodiscard]] bool IsOutputInhibited() const noexcept {
        return outputs_inhibited_.load(std::memory_order_acquire);
    }
 
    void GetEnablePinStates(bool& max_enable, bool& tle_enable) const noexcept;
 
    //==========================================================================
    // CHANNEL ENABLE / DISABLE (unified for both drivers)
    //==========================================================================
 
    [[nodiscard]] hf_valve_err_t EnableChannel(ValveChannel channel) noexcept;
 
    [[nodiscard]] hf_valve_err_t DisableChannel(ValveChannel channel) noexcept;
 
    [[nodiscard]] hf_valve_err_t EnableChannelsMask(uint16_t mask) noexcept;
 
    [[nodiscard]] hf_valve_err_t DisableAllChannels() noexcept;
 
    [[nodiscard]] bool IsChannelEnabled(ValveChannel channel) const noexcept;
 
    //==========================================================================
    // SOLENOID CONFIGURATION (MAX22200-specific)
    //==========================================================================
 
    [[nodiscard]] hf_valve_err_t ConfigureSolenoidCdr(ValveChannel channel,
                                            uint16_t hit_ma, uint16_t hold_ma,
                                            float hit_time_ms) noexcept;
 
    [[nodiscard]] hf_valve_err_t ConfigureSolenoidVdr(ValveChannel channel,
                                            float hit_duty_pct, float hold_duty_pct,
                                            float hit_time_ms) noexcept;
 
    //==========================================================================
    // PROPORTIONAL CONFIGURATION (TLE92466ED-specific)
    //==========================================================================
 
    [[nodiscard]] hf_valve_err_t SetProportionalCurrent(ValveChannel channel, uint16_t current_ma) noexcept;
 
    [[nodiscard]] hf_valve_err_t ConfigureProportionalPwm(ValveChannel channel,
                                                float frequency_hz) noexcept;
 
    [[nodiscard]] hf_valve_err_t ConfigureProportionalDither(ValveChannel channel,
                                                   float amplitude_ma,
                                                   float frequency_hz) noexcept;
 
    //==========================================================================
    // STATUS & FAULT MANAGEMENT
    //==========================================================================
 
    [[nodiscard]] bool HasFault() noexcept;
 
    [[nodiscard]] hf_valve_err_t ClearAllFaults() noexcept;
 
    [[nodiscard]] bool HasSolenoidFault() noexcept;
 
    [[nodiscard]] bool HasProportionalFault() noexcept;
 
    [[nodiscard]] hf_valve_err_t GetSolenoidFaults(max22200::FaultStatus& faults) noexcept;
 
    [[nodiscard]] hf_valve_err_t GetProportionalFaults(tle92466ed::FaultReport& report) noexcept;
 
    //==========================================================================
    // CHANNEL INFORMATION
    //==========================================================================
 
    [[nodiscard]] const ValveChannelState* GetChannelState(ValveChannel channel) const noexcept;
 
    [[nodiscard]] const ValveChannelInfo* GetChannelInfo(std::string_view name) const noexcept;
 
    [[nodiscard]] ValveChannel FindChannel(std::string_view name) const noexcept;
 
    //==========================================================================
    // DIRECT DRIVER ACCESS (for advanced use)
    //==========================================================================
 
    [[nodiscard]] Max22200Handler* GetMax22200Handler() noexcept;
 
    [[nodiscard]] Tle92466edHandler* GetTle92466Handler() noexcept;
 
    //==========================================================================
    // DIAGNOSTICS
    //==========================================================================
 
    [[nodiscard]] hf_valve_err_t GetLastError() const noexcept { return last_error_.load(std::memory_order_acquire); }
 
    [[nodiscard]] hf_valve_err_t GetSystemDiagnostics(ValveSystemDiagnostics& diag) const noexcept;
 
    void DumpStatistics() const noexcept;
 
private:
    ValveManager() noexcept;
    ~ValveManager() = default;
 
    hf_valve_err_t Initialize() noexcept;
    flux::hal::ManagerError InitializeMax22200() noexcept;
    flux::hal::ManagerError InitializeTle92466() noexcept;
 
    hf_valve_err_t DisableAllLocked() noexcept;
 
    void ReleaseDriversLocked() noexcept;
 
    hf_valve_err_t Record(hf_valve_err_t result) const noexcept {
        if (!HfValveErrOk(result)) {
            last_error_.store(result, std::memory_order_release);
        }
        return result;
    }
 
    [[nodiscard]] static bool ResolveChannel(ValveChannel channel,
                                             ValveDriverType& driver_type,
                                             uint8_t& hw_channel) noexcept;
 
 
    //==========================================================================
    // HANDLER INSTANCES — members, constructed in place at bring-up (no heap)
    //==========================================================================
 
    std::optional<Max22200Handler> max22200_;
    bool max22200_valid_{false};
 
    std::optional<Tle92466edHandler> tle92466_;
    bool tle92466_valid_{false};
 
    //==========================================================================
    // CHANNEL STATE — fixed-size, stack-allocated
    //==========================================================================
 
    std::array<ValveChannelState, static_cast<size_t>(ValveChannel::CHANNEL_COUNT)> channel_states_{};
 
    std::atomic<bool> initialized_{false};
    std::atomic<bool> outputs_inhibited_{false};  
    std::atomic<flux::hal::ManagerError> manager_error_{flux::hal::ManagerError::NotInitialized};
    mutable std::atomic<hf_valve_err_t> last_error_{hf_valve_err_t::VALVE_SUCCESS};
    mutable RtosMutex mutex_;
};
 
//==============================================================================
// CONVENIENCE
//==============================================================================
 
[[nodiscard]] inline ValveManager& GetValveManager() noexcept {
    return ValveManager::GetInstance();
}
 
#endif // FLUX_VALVE_MANAGER_H_