WhmDelegate.h

/*
 *
 *    Copyright (c) 2024 Project CHIP Authors
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

#pragma once

#include <app-common/zap-generated/cluster-objects.h>
#include <app/clusters/water-heater-management-server/water-heater-management-server.h>

#include <protocols/interaction_model/StatusCode.h>

namespace chip {
namespace app {
namespace Clusters {
namespace WaterHeaterManagement {

class WhmManufacturer;

enum HeatingOp
{
    TurnHeatingOn,
    TurnHeatingOff,
    LeaveHeatingUnchanged
};

// This is an application level delegate to handle operational state commands according to the specific business logic.
class WaterHeaterManagementDelegate : public WaterHeaterManagement::Delegate
{
public:
    WaterHeaterManagementDelegate(EndpointId clustersEndpoint);

    virtual ~WaterHeaterManagementDelegate() = default;

    void SetWaterHeaterManagementInstance(WaterHeaterManagement::Instance & instance);

    void SetWhmManufacturer(WhmManufacturer & whmManufacturer);

    /*********************************************************************************
     *
     * Methods implementing the WaterHeaterManagement::Delegate interface
     *
     *********************************************************************************/

    /**
     * @brief Delegate should implement a handler to start boosting the water
     *        temperature as required. Upon receipt, the Water Heater SHALL
     *        transition into the BOOST state, which SHALL cause the water in
     *        the tank (or the TargetPercentage of the water, if included) to be
     *        heated towards the set point (or the TemporarySetpoint, if
     *        included), which in turn may cause a call for heat, even if the
     *        mode is OFF, or is TIMED and it is during one of the Off periods.
     *
     * @param duration           Indicates the time period in seconds for which
     *                           the BOOST state is activated before it
     *                           automatically reverts to the previous mode
     *                           (e.g. OFF, MANUAL or TIMED).
     *
     * @param oneShot            Indicates whether the BOOST state should be
     *                           automatically canceled once the hot water has
     *                           first reached the set point temperature (or the
     *                           TemporarySetpoint temperature, if specified)
     *                           for the TargetPercentage (if specified).
     *
     * @param emergencyBoost     Indicates that the consumer wants the water to
     *                           be heated as quickly as practicable. This MAY
     *                           cause multiple heat sources to be activated
     *                           (e.g. a heat pump and direct electric heating
     *                           element).
     *
     * @param temporarySetpoint  Indicates the target temperature to which to
     *                           heat the hot water for this Boost command. It
     *                           SHALL be used instead of the normal set point
     *                           temperature whilst the BOOST state is active.
     *
     * @param targetPercentage   If the tank supports the TankPercent feature,
     *                           this field indicates the amount of water that
     *                           SHALL be heated by this Boost command before
     *                           the heater is switched off.
     *
     * @param targetReheat       If the tank supports the TankPercent feature,
     *                           and the heating by this Boost command has
     *                           ceased because the TargetPercentage of the
     *                           water in the tank has been heated to the set
     *                           point (or TemporarySetpoint if included), this
     *                           field indicates the percentage to which the hot
     *                           water in the tank SHALL be allowed to fall
     *                           before again beginning to reheat it.
     *
     * @return  Success if the boost command is accepted; otherwise the command
     * SHALL be rejected with appropriate error.
     */
    Protocols::InteractionModel::Status HandleBoost(uint32_t duration, Optional<bool> oneShot, Optional<bool> emergencyBoost,
                                                    Optional<int16_t> temporarySetpoint, Optional<Percent> targetPercentage,
                                                    Optional<Percent> targetReheat) override;

    /**
     * @brief Delegate should implement a handler to cancel a boost command.
     *        Upon receipt, the Water Heater SHALL transition back from the
     *        BOOST state to the previous mode (e.g. OFF, MANUAL or TIMED).
     *
     * @return It should report SUCCESS if successful and FAILURE otherwise.
     */
    Protocols::InteractionModel::Status HandleCancelBoost() override;

    // ------------------------------------------------------------------
    // Get attribute methods
    BitMask<WaterHeaterHeatSourceBitmap> GetHeaterTypes() override;
    BitMask<WaterHeaterHeatSourceBitmap> GetHeatDemand() override;
    uint16_t GetTankVolume() override;
    Energy_mWh GetEstimatedHeatRequired() override;
    Percent GetTankPercentage() override;
    BoostStateEnum GetBoostState() override;

    // ------------------------------------------------------------------
    // Set attribute methods
    void SetHeaterTypes(BitMask<WaterHeaterHeatSourceBitmap> heaterTypes);
    void SetHeatDemand(BitMask<WaterHeaterHeatSourceBitmap> heatDemand);
    void SetTankVolume(uint16_t tankVolume);
    void SetEstimatedHeatRequired(Energy_mWh estimatedHeatRequired);
    void SetTankPercentage(Percent tankPercentage);
    void SetBoostState(BoostStateEnum boostState);

    /***************************************************************************
     *
     * WaterHeaterManagementDelegate specific methods
     *
     ***************************************************************************/

    /**
     * @brief Set the Water Header Mode and act accordingly.
     *
     * @param mode  The Water Heater Mode (e.g. OFF, MANUAL or TIMED).
     */
    Protocols::InteractionModel::Status SetWaterHeaterMode(uint8_t mode);

    /**
     * @brief Set the water temperature of the tank
     *
     * @param waterTemperature  The water temperature in 100th's Celsius
     */
    void SetWaterTemperature(int16_t waterTemperature);

    /**
     * @brief Set the target water temperature of the tank
     *
     * @param targetWaterTemperature  The water temperature in 100th's Celsius
     */
    void SetTargetWaterTemperature(int16_t targetWaterTemperature);

    /**
     * @brief Determine whether the heating sources need to be turned on or off or left unchanged.
     *
     * @return Success if the heating was successfully turned on or off or left unchanged otherwise an error
     *         code is returned if turning the heating on or off failed.
     */
    Protocols::InteractionModel::Status ChangeHeatingIfNecessary();

    /**
     * @brief Static timer callback for when Boost timer expires.
     */
    static void BoostTimerExpiry(System::Layer * systemLayer, void * delegate);

    /**
     * @brief Object timer callback for when Boost timer expires.
     */
    void HandleBoostTimerExpiry();

    /**
     * Determines whether the tank water temperature has reached the target
     * temperature.
     *
     * @return Returns True is tank water temperature has reached the target
     * temperature, False otherwise.
     */
    bool HasWaterTemperatureReachedTarget() const;

    /**
     * Simulates water being drawn from the water tank.
     *
     * @param percentageReplaced  The % of water being replaced with water with
     * a temperature of replacedWaterTemperature.
     *
     * @param replacedWaterTemperature  The temperature of the
     * percentageReplaced water.
     */
    void DrawOffHotWater(Percent percentageReplaced, int16_t replacedWaterTemperature);

    /**
     * Set the temperature of the cold water that fills the tank as the hot water
     * is drawn off.
     *
     * @param coldWaterTemperature  The cold water temperature in 100th of a C
     */
    void SetColdWaterTemperature(int16_t coldWaterTemperature);

private:
    /**
     * Return the target temperature.
     * If a boost command is in progress and has a mBoostTemporarySetpoint value use that as the
     * target temperature otherwise use the temperature set via SetTargetWaterTemperature().
     *
     * @return the target temperature
     */
    int16_t GetActiveTargetWaterTemperature() const;

    /**
     * @brief Calculate the percentage of the water in the tank at the target
     *        temperature.
     *
     * @return  Percentage of water at the target temperature
     */
    uint8_t CalculateTankPercentage() const;

    /**
     * @brief Determine whether heating needs to be turned on or off or left as
     * is.
     *
     * @param heatingOp[out]  Set as determined whether heating needs to be
     * turned on/off or left unchanged.
     *
     * @return  Success if the heating operation could be determined otherwise
     * returns with appropriate error.
     */
    Protocols::InteractionModel::Status DetermineIfChangingHeatingState(HeatingOp & heatingOp);

private:
    /***************************************************************************
     *
     * WaterHeaterManagementDelegate specific attributes
     *
     ***************************************************************************/

    // Need the following so can determine which features are supported
    WaterHeaterManagement::Instance * mpWhmInstance;

    // Pointer to the manufacturer specific object which understand the hardware
    WhmManufacturer * mpWhmManufacturer;

    // Target water temperature in 100ths of a C
    int16_t mTargetWaterTemperature;

    // Actual water temperature in 100ths of a C
    int16_t mWaterTemperature;

    // The cold water temperature in 100ths of a C
    int16_t mColdWaterTemperature;

    // Boost command parameters

    // This field SHALL indicate whether the BOOST state should be automatically
    // canceled once the hot water has first reached the set point temperature
    // (or the TemporarySetpoint temperature, if specified) for the
    // TargetPercentage (if specified).
    Optional<bool> mBoostOneShot;

    // This field indicates that the consumer wants the water to be heated as
    // quickly as practicable. This MAY cause multiple heat sources to be
    // activated (e.g. a heat pump and direct electric heating element).
    Optional<bool> mBoostEmergencyBoost;

    // This field indicates the target temperature to which to heat the hot
    // water for this Boost command. It SHALL be used instead of the normal set
    // point temperature whilst the BOOST state is active.
    Optional<int16_t> mBoostTemporarySetpoint;

    // If the tank supports the TankPercent feature, this field indicates the
    // amount of water that SHALL be heated by this Boost command before the
    // heater is switched off. This field is optional, however it SHALL be
    // included if the TargetReheat field is included.
    Optional<Percent> mBoostTargetPercentage;

    // If the tank supports the TankPercent feature, and the heating by this
    // Boost command has ceased because the TargetPercentage of the water in the
    // tank has been heated to the set point (or TemporarySetpoint if included),
    // this field indicates the percentage to which the hot water in the tank
    // SHALL be allowed to fall before again beginning to reheat it. For example
    // if the TargetPercentage was 80%, and the TargetReheat was 40%, then after
    // initial heating to 80% hot water, the tank may have hot water drawn off
    // until only 40% hot water remains. At this point the heater will begin to
    // heat back up to 80% of hot water. If this field and the OneShot field
    // were both omitted, heating would begin again after any water draw which
    // reduced the TankPercentage below 80%.
    Optional<Percent> mBoostTargetReheat;

    // Track whether the water temperature has reached the water temperature
    // specified in the boost command. Used in conjunction with the boost
    // command boostTargetReheat parameter
    bool mBoostTargetTemperatureReached;

    /*********************************************************************************
     *
     * Member variables implementing the WaterHeaterManagement::Delegate interface
     *
     *********************************************************************************/

    // This attribute SHALL indicate the methods to call for heat that the
    // controller supports. If a bit is set then the controller supports the
    // corresponding method.
    BitMask<WaterHeaterHeatSourceBitmap> mHeaterTypes;

    // This attribute SHALL indicate if the controller is asking for heat. If a
    // bit is set then the corresponding call for heat is active.
    BitMask<WaterHeaterHeatSourceBitmap> mHeatDemand;

    // This attribute SHALL indicate the volume of water that the hot water tank
    // can hold (in units of Litres). This allows an energy management system to
    // estimate the required heating energy needed to reach the target
    // temperature.
    uint16_t mTankVolume;

    // This attribute SHALL indicate the estimated heat energy needed to raise
    // the water temperature to the target setpoint. This can be computed by
    // taking the specific heat capacity of water (4182 J/kg °C) and by knowing
    // the current temperature of the water, the tank volume and target
    // temperature.
    Energy_mWh mEstimatedHeatRequired;

    // This attribute SHALL indicate an approximate level of hot water stored in
    // the tank, which may help consumers understand the amount of hot water
    // remaining in the tank.
    Percent mTankPercentage;

    // This attribute SHALL indicate if the BOOST state, as triggered by a Boost
    // command, is currently active.
    BoostStateEnum mBoostState;
};

} // namespace WaterHeaterManagement
} // namespace Clusters
} // namespace app
} // namespace chip