relay.h

// SPDX-FileCopyrightText: AC SOFTWARE SP. Z O.O.
// SPDX-License-Identifier: GPL-2.0-or-later
 
/* Relay class
 * This class is used to control any type of relay that can be controlled
 * by setting LOW or HIGH output on selected GPIO.
 */
 
#ifndef SRC_SUPLA_CONTROL_RELAY_H_
#define SRC_SUPLA_CONTROL_RELAY_H_
 
#include <stdint.h>
 
#include "../action_handler.h"
#include "../channel_element.h"
#include "../io.h"
#include "weekly_schedule_component.h"
 
#define STATE_ON_INIT_RESTORED_OFF -3
#define STATE_ON_INIT_RESTORED_ON  -2
#define STATE_ON_INIT_RESTORE      -1
#define STATE_ON_INIT_OFF          0
#define STATE_ON_INIT_ON           1
 
#define RELAY_FLAGS_ON               (1 << 0)
#define RELAY_FLAGS_STAIRCASE        (1 << 1)
#define RELAY_FLAGS_IMPULSE_FUNCTION (1 << 2)  // i.e. gate, door, gateway
#define RELAY_FLAGS_OVERCURRENT      (1 << 3)
#define RELAY_FLAGS_AUTOMATIC_MODE   (1 << 5)
 
#define RELAY_STORED_MODE_NOT_SET    0
#define RELAY_STORED_MODE_AUTOMATIC  1
#define RELAY_STORED_MODE_FORCED_OFF 2
#define RELAY_STORED_MODE_FORCED_ON  3
 
namespace Supla {
namespace Io {
struct IoPin;
}
 
namespace Control {
class Button;
class RelayWeeklySchedule;
 
class Relay : public ChannelElement, public ActionHandler {
 public:
  friend class RelayWeeklySchedule;
 
  union RelayFlags {
    struct {
      uint8_t relayOn : 1;
      uint8_t staircaseFunction : 1;
      uint8_t impulseFunction : 1;
      uint8_t overcurrent : 1;
      uint8_t weeklySchedule : 1;
      // AUTOMATIC remains encoded as bit 5 for OTA compatibility.
      uint8_t operatingMode : 2;
      uint8_t reserved : 1;
    } flags;
    uint8_t rawValue = 0;
  };
 
  static_assert(sizeof(RelayFlags) == sizeof(uint8_t),
                "Flags size must be 1 byte");
 
  explicit Relay(Supla::Io::IoPin outputPin,
                 _supla_int_t functions =
                     (0xFF ^ SUPLA_BIT_FUNC_CONTROLLINGTHEROLLERSHUTTER));
  explicit Relay(Supla::Io::Base *io,
                 int pin,
                 bool highIsOn = true,
                 _supla_int_t functions =
                     (0xFF ^ SUPLA_BIT_FUNC_CONTROLLINGTHEROLLERSHUTTER));
  explicit Relay(int pin,
                 bool highIsOn = true,
                 _supla_int_t functions =
                     (0xFF ^ SUPLA_BIT_FUNC_CONTROLLINGTHEROLLERSHUTTER));
 
  virtual ~Relay();
 
  virtual Relay &setDefaultStateOn();
  virtual Relay &setDefaultStateOff();
  virtual Relay &setDefaultStateRestore();
  virtual Relay &setPreloadStateOnSoftReset(bool enabled = true);
  virtual Relay &keepTurnOnDuration(bool keep = true);  // DEPREACATED
 
  [[deprecated("Use IoPin::writeActive/writeInactive instead")]] virtual uint8_t
  pinOnValue();
  [[deprecated("Use IoPin::writeActive/writeInactive instead")]] virtual uint8_t
  pinOffValue();
  virtual void turnOn(_supla_int_t duration = 0);
  virtual void turnOff(_supla_int_t duration = 0);
  virtual bool isOn();
  virtual void toggle(_supla_int_t duration = 0);
 
  void attach(Supla::Control::Button *);
 
  void handleAction(int event, int action) override;
 
  void onLoadConfig(SuplaDeviceClass *sdc) override;
  void purgeConfig() override;
  void onInit() override;
  void onLoadState() override;
  void onSaveState() override;
  void iterateAlways() override;
  bool iterateConnected() override;
  int32_t handleNewValueFromServer(TSD_SuplaChannelNewValue *newValue) override;
  void onRegistered(Supla::Protocol::SuplaSrpc *suplaSrpc) override;
  Supla::ApplyConfigResult applyChannelConfig(TSD_ChannelConfig *result,
                                              bool local = false) override;
  void fillChannelConfig(void *channelConfig,
                         int *size,
                         uint8_t configType) override;
  bool getRemainingCountdownTimerSec(uint32_t *remainingSec) const override;
 
  // Method is used by external integrations to prepare TSD_SuplaChannelNewValue
  // value for specific channel type (i.e. to prefill durationMS field when
  // required)
  void fillSuplaChannelNewValue(TSD_SuplaChannelNewValue *value) override;
 
  unsigned _supla_int_t getStoredTurnOnDurationMs();
  void setStoredTurnOnDurationMs(uint32_t durationMs);
 
  bool isStaircaseFunction(uint32_t functionToCheck = 0) const;
  bool isImpulseFunction(uint32_t functionToCheck = 0) const;
  void disableCountdownTimerFunction();
  void enableCountdownTimerFunction();
  bool isCountdownTimerFunctionEnabled() const;
  void setMinimumAllowedDurationMs(uint32_t durationMs);
 
  static void setRelayStorageSaveDelay(uint32_t delayMs);
 
  bool isDefaultRelatedMeterChannelSet() const;
  uint32_t getCurrentValueFromMeter() const;
  void setDefaultRelatedMeterChannelNo(int channelNo);
  void setTurnOffWhenEmptyAggregator(bool turnOff);
 
  void setOvercurrentThreshold(uint32_t value);
 
  uint32_t getOvercurrentThreshold() const {
    return overcurrentThreshold;
  }
 
  void setOvercurrentMaxAllowed(uint32_t value);
 
  uint32_t getOvercurrentMaxAllowed() const {
    return overcurrentMaxAllowed;
  }
 
  void setDefaultStaircaseDurationMs(uint16_t durationMs) {
    defaultStaircaseDurationMs = durationMs;
  }
 
  void setDefaultImpulseDurationMs(uint16_t durationMs) {
    defaultImpulseDurationMs = durationMs;
  }
 
  bool setRuntimeFunction(uint32_t channelFunction) override;
  bool setAndSaveFunction(uint32_t channelFunction) override;
 
  void setRestartTimerOnToggle(bool restart);
 
  bool isRestartTimerOnToggle() const;
 
  bool isFullyInitialized() const;
 
  void enableCyclicMode(uint32_t turnOnTimeMs, uint32_t turnOffTimeMs);
  void disableCyclicMode();
  bool isCyclicMode() const;
 
  bool isWeeklyScheduleSupported() const;
  Relay &setWeeklyScheduleAvailable(bool available = true);
  bool isWeeklyScheduleAvailable() const;
  Relay &setAutomaticModeSupported(bool supported = true);
  bool isAutomaticModeSupported() const;
  bool isAutomaticMode() const;
  bool setAutomaticMode(bool enabled);
  bool setWeeklyScheduleController(
      WeeklyScheduleController *controller,
      WeeklyScheduleConfigHandler *configHandler = nullptr,
      WeeklyScheduleProgramSource *programSource = nullptr);
 
 protected:
  Relay(Supla::Io::IoPin outputPin,
        _supla_int_t functions,
        Supla::Channel &externalChannel,
        ElementMode mode);
 
  struct ButtonListElement {
    Supla::Control::Button *button = nullptr;
    ButtonListElement *next = nullptr;
  };
 
  void applyDuration(int32_t durationMs, bool turnOn);
  void setOvercurrentThreshold(uint32_t value, bool local);
 
  virtual void setNewChannelValue(bool value);
  virtual void fillDefaultWeeklySchedule(
      TChannelConfig_WeeklySchedule *schedule);
  virtual bool canUseWeeklySchedule() const;
  // Registration capability. Overrides must not depend on the function
  // currently selected on the server.
  virtual bool isWeeklyScheduleProgramModeSupported(uint8_t mode) const;
  bool isWeeklyScheduleProgramModeAvailable(uint8_t mode) const;
  // Runtime applicability after the server-selected function is known.
  bool isWeeklyScheduleProgramModeApplicable(uint8_t mode) const;
  bool hasAnyWeeklyScheduleProgramModeAvailable() const;
  virtual void iterateAutomaticMode();
 
  void saveConfig() const;
  void loadRelayConfigOnly();
  bool ensureNativeWeeklyScheduleController();
  void updateWeeklyScheduleCapabilities();
  void updateAutomaticModeCapability();
  void purgeRelayConfigOnly();
  void updateTimerValue();
  void emitCountdownTimerActionIfNeeded();
  void updateRelayHvacAggregator();
  bool isManualActionAllowed(bool turnOn) const;
  bool isManualForcedModeSupported() const;
  bool setManualForcedMode(uint8_t mode);
  void disableWeeklySchedule();
  void applyWeeklyScheduleProgram(uint8_t programMode, bool programChanged);
  virtual bool applyWeeklyScheduleState(bool on);
  void notifyWeeklyScheduleManualAction();
  uint32_t durationMs = 0;
  uint32_t storedTurnOnDurationMs = 0;
  uint32_t durationTimestamp = 0;
  uint32_t turnOffDurationForCycle = 0;
  uint16_t defaultStaircaseDurationMs = 10000;
  uint16_t defaultImpulseDurationMs = 500;
 
  uint32_t overcurrentThreshold = 0;   // 0.01 A
  uint32_t overcurrentMaxAllowed = 0;  // 0.01 A
  uint32_t overcurrentActiveTimestamp = 0;
  uint32_t overcurrentCheckTimestamp = 0;
 
  uint32_t timerUpdateTimestamp = 0;
  uint32_t lastCountdownTimerRemainingSec = UINT32_MAX;
  uint32_t postponeCommTimestamp = 0;
 
  ButtonListElement *buttonList = nullptr;
 
  uint16_t minimumAllowedDurationMs = 0;
  int16_t defaultRelatedMeterChannelNo = -1;
 
  // Runtime-only flags; state storage uses a separate representation.
  struct RuntimeFlags {
    RuntimeFlags()
        : keepTurnOnDurationMs(false),
          turnOffWhenEmptyAggregator(true),
          initDone(false),
          restartTimerOnToggle(false),
          skipInitialStateSetting(false),
          preloadStateOnSoftReset(false),
          automaticModeSupported(false),
          weeklyScheduleAvailable(false) {}
 
    uint8_t keepTurnOnDurationMs : 1;
    uint8_t turnOffWhenEmptyAggregator : 1;
    uint8_t initDone : 1;
    uint8_t restartTimerOnToggle : 1;
    uint8_t skipInitialStateSetting : 1;
    uint8_t preloadStateOnSoftReset : 1;
    uint8_t automaticModeSupported : 1;
    // Native weekly schedule remains opt-in.
    uint8_t weeklyScheduleAvailable : 1;
  };
 
  static_assert(sizeof(RuntimeFlags) == sizeof(uint8_t),
                "Relay runtime flags must fit in uint8_t");
 
  RuntimeFlags runtimeFlags;
 
  int8_t stateOnInit = STATE_ON_INIT_OFF;
  Supla::Io::IoPin outputPin;
  WeeklyScheduleComponents weeklyScheduleComponents;
 
  static uint16_t relayStorageSaveDelay;
};
 
};  // namespace Control
};  // namespace Supla
 
#endif  // SRC_SUPLA_CONTROL_RELAY_H_