utils_relay.h

Go to the documentation of this file.

 
#ifndef UTILS_RELAY_H
#define UTILS_RELAY_H
 
#include "types.h"
#include "type_traits.hpp"
#include "debug.h"
 
#include "config_system.h"
#include "ewma_avg.hpp"
#include "utils_pins.h"

class relayOutput
{
public:
  constexpr relayOutput() = delete;

  explicit constexpr relayOutput(const uint8_t _relay_pin)
    : relay_pin{ _relay_pin }
  {
  }

  constexpr relayOutput(uint8_t _relay_pin, int16_t _surplusThreshold, int16_t _importThreshold)
    : relay_pin{ _relay_pin }, surplusThreshold{ -abs(_surplusThreshold) }, importThreshold{ _importThreshold }
  {
  }

  constexpr relayOutput(uint8_t _relay_pin, int16_t _surplusThreshold, int16_t _importThreshold, uint16_t _minON, uint16_t _minOFF)
    : relay_pin{ _relay_pin }, surplusThreshold{ -abs(_surplusThreshold) }, importThreshold{ _importThreshold }, minON{ _minON * 60 }, minOFF{ _minOFF * 60 }
  {
  }

  constexpr auto get_pin() const
  {
    return relay_pin;
  }

  constexpr auto get_surplusThreshold() const
  {
    return -surplusThreshold;
  }

  constexpr auto get_importThreshold() const
  {
    return importThreshold;
  }

  constexpr auto get_minON() const
  {
    return minON;
  }

  constexpr auto get_minOFF() const
  {
    return minOFF;
  }

  auto isRelayON() const
  {
    return relayIsON;
  }

  void inc_duration() const
  {
    if (duration < UINT16_MAX)
    {
      ++duration;
    }
  }

  bool proceed_relay(const int32_t currentAvgPower, uint16_t& overrideBitmask) const
  {
    const bool isOverrideActive = bit_read(overrideBitmask, relay_pin);
 
    // To avoid changing sign, surplus is a negative value
    // Turn ON if surplus threshold is met OR if override is active
    if (currentAvgPower < surplusThreshold || isOverrideActive)
    {
      bit_clear(overrideBitmask, relay_pin);  // Clear override bit if it was set
      return try_turnON();
    }
 
    // Handle both positive and negative import thresholds
    if (importThreshold >= 0)
    {
      // Positive threshold: turn OFF when importing > threshold (normal mode)
      if (currentAvgPower > importThreshold)
      {
        return try_turnOFF();
      }
    }
    else
    {
      // Negative threshold: turn OFF when surplus < abs(threshold) (battery mode)
      if (currentAvgPower > importThreshold)  // importThreshold is negative, so this checks surplus < abs(threshold)
      {
        return try_turnOFF();
      }
    }
 
    return false;
  }

  void printRelayConfiguration(uint8_t idx) const
  {
    Serial.print(F("\tRelay configuration: #"));
    Serial.println(idx + 1);
 
    Serial.print(F("\t\tPin is "));
    Serial.println(get_pin());
 
    Serial.print(F("\t\tSurplus threshold: "));
    Serial.println(get_surplusThreshold());
 
    Serial.print(F("\t\tImport threshold: "));
    Serial.print(get_importThreshold());
    if (get_importThreshold() >= 0)
    {
      Serial.println(F(" (import mode)"));
    }
    else
    {
      Serial.print(F(" (surplus mode: turn OFF when surplus < "));
      Serial.print(-get_importThreshold());
      Serial.println(F("W)"));
    }
 
    Serial.print(F("\t\tMinimum working time in minutes: "));
    Serial.println(get_minON() / 60);
 
    Serial.print(F("\t\tMinimum stop time in minutes: "));
    Serial.println(get_minOFF() / 60);
  }
 
private:
  bool try_turnON() const
  {
    if (relayIsON || duration < minOFF)
    {
      return false;
    }
 
    setPinON(relay_pin);
 
    DBUGLN(F("Relay turned ON!"));
 
    relayIsON = true;
    duration = 0;
 
    return true;
  }

  bool try_turnOFF() const
  {
    if (!relayIsON || duration < minON)
    {
      return false;
    }
 
    setPinOFF(relay_pin);
 
    DBUGLN(F("Relay turned OFF!"));
 
    relayIsON = false;
    duration = 0;
 
    return true;
  }
 
private:
  const uint8_t relay_pin{ unused_pin };   
  const int16_t surplusThreshold{ -1000 }; 
  const int16_t importThreshold{ 200 };    
  const uint16_t minON{ 5 * 60 };          
  const uint16_t minOFF{ 5 * 60 };         
 
  mutable uint16_t duration{ 0 };  
  mutable bool relayIsON{ false }; 
};

template< uint8_t N, uint8_t D = 10 >
class RelayEngine
{
public:
  explicit constexpr RelayEngine(const relayOutput (&ref)[N])
    : relay(ref)
  {
  }

  constexpr RelayEngine(integral_constant< uint8_t, D > /* ic */, const relayOutput (&ref)[N])
    : relay(ref)
  {
  }

  constexpr auto size() const
  {
    return N;
  }

  constexpr const auto& get_relay(uint8_t idx) const
  {
    return relay[idx];
  }

  inline static auto get_average()
  {
    return ewma_average.getAverageT();  // Use TEMA for better cloud immunity
  }

  inline static void update_average(int16_t currentPower)
  {
    ewma_average.addValue(currentPower);
  }

#if defined(__DOXYGEN__)
  void inc_duration() const;
#else
  void inc_duration() const __attribute__((optimize("-O3")));
#endif

  void proceed_relays(uint16_t& overrideBitmask) const
  {
    if (settle_change != 0)
    {
      // A relay has been toggle less than a minute ago, wait until changes take effect
      return;
    }
 
    if (ewma_average.getAverageT() > 0)
    {
      // Currently importing, try to turn OFF some relays
      uint8_t idx{ N };
      do
      {
        if (relay[--idx].proceed_relay(ewma_average.getAverageT(), overrideBitmask))
        {
          settle_change = 60;
          return;
        }
      } while (idx);
    }
    else
    {
      // Remaining surplus, try to turn ON more relays
      uint8_t idx{ 0 };
      do
      {
        if (relay[idx].proceed_relay(ewma_average.getAverageT(), overrideBitmask))
        {
          settle_change = 60;
          return;
        }
      } while (++idx < N);
    }
  }

  void printRelayEngineConfiguration() const
  {
    Serial.println(F("*** Relay(s) configuration ***"));
    Serial.print(F("\tSliding average: "));
    Serial.println(D);
 
    for (uint8_t i = 0; i < N; ++i)
    {
      relay[i].printRelayConfiguration(i);
    }
  }
 
private:
  const relayOutput relay[N]; 
 
  mutable uint8_t settle_change{ 60 }; 
 
  static inline EWMA_average< D * 60 / DATALOG_PERIOD_IN_SECONDS > ewma_average; 
};
 
template< uint8_t N, uint8_t D > void RelayEngine< N, D >::inc_duration() const
{
  uint8_t idx{ N };
  do
  {
    relay[--idx].inc_duration();
  } while (idx);
 
  if (settle_change)
  {
    --settle_change;
  }
}
 
// Deduction guides for automatic template parameter deduction
template< uint8_t N >
RelayEngine(const relayOutput (&)[N]) -> RelayEngine< N, 10 >;
 
template< uint8_t N, uint8_t D >
RelayEngine(integral_constant< uint8_t, D >, const relayOutput (&)[N]) -> RelayEngine< N, D >;
 
#endif /* UTILS_RELAY_H */