/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */

/*** THIS FILE IS GENERATED, DO NOT EDIT ***/

import { Resource } from "#models/Resource.js";

Resource.add(
    {
        tag: "cluster", name: "WaterHeaterManagement", pics: "EWATERHTR", xref: "cluster§9.5",

        details: "This cluster is used to allow clients to control the operation of a hot water heating appliance so " +
            "that it can be used with energy management." +
            "\n" +
            "Heating of hot water is one of the main energy uses in homes, and when coupled with the Energy " +
            "Management cluster, it can help consumers save cost (e.g. using power at cheaper times or from local " +
            "solar PV generation).",

        children: [
            {
                tag: "attribute", name: "FeatureMap", xref: "cluster§9.5.4",

                children: [
                    { tag: "field", name: "EM", details: "Allows energy management control of the tank" },
                    {
                        tag: "field", name: "TP",
                        details: "Supports monitoring the percentage of hot water in the tank"
                    }
                ]
            },

            {
                tag: "attribute", name: "HeaterTypes", xref: "cluster§9.5.7.1",
                details: "Indicates the heat sources that the water heater can call on for heating. If a bit is set then the " +
                    "water heater supports the corresponding heat source."
            },
            {
                tag: "attribute", name: "HeatDemand", xref: "cluster§9.5.7.2",
                details: "Indicates if the water heater is heating water. If a bit is set then the corresponding heat source " +
                    "is active."
            },

            {
                tag: "attribute", name: "TankVolume", xref: "cluster§9.5.7.3",
                details: "Indicates 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."
            },

            {
                tag: "attribute", name: "EstimatedHeatRequired", xref: "cluster§9.5.7.4",

                details: "Indicates 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." +
                    "\n" +
                    "> [!NOTE]" +
                    "\n" +
                    "> For example, if the target temperature was 60°C, the current temperature was 20°C and the tank " +
                    "volume was 100L: Mass of water = 1kg per Litre Total Mass = 100 x 1kg = 100kg Δ Temperature = " +
                    "(target temperature - current temperature) = (60°C - 20°C) = 40°C Energy required to heat the " +
                    "water to 60°C = 4182 x 40 x 100 = 16,728,000 J Converting Joules in to Wh of heat (divide by " +
                    "3600): = 16,728,000 J / 3600 = 4647 Wh (4.65kWh)" +
                    "\n" +
                    "If the TankPercent feature is supported, then this estimate shall also take into account the " +
                    "percentage of the water in the tank which is already hot." +
                    "\n" +
                    "> [!NOTE]" +
                    "\n" +
                    "> NOTE: The electrical energy required to heat the water depends on the heating system used to heat " +
                    "the water. For example, a direct electric immersion heating element can be close to 100% " +
                    "efficient, so the electrical energy needed to heat the hot water is nearly the same as the " +
                    "  EstimatedHeatEnergyRequired. However some forms of heating, such as an air-source heat pump which " +
                    "extracts heat from ambient air, requires much less electrical energy to heat hot water. Heat pumps " +
                    "can be produce 3kWh of heat output for 1kWh of electrical energy input. The conversion between " +
                    "heat energy and electrical energy is outside the scope of this cluster."
            },

            {
                tag: "attribute", name: "TankPercentage", xref: "cluster§9.5.7.5",

                details: "Indicates an approximate level of hot water stored in the tank, which might help consumers " +
                    "understand the amount of hot water remaining in the tank. The accuracy of this attribute is " +
                    "manufacturer specific." +
                    "\n" +
                    "In most hot water tanks, there is a stratification effect where the hot water layer rests above a " +
                    "cooler layer of water below. For this reason cold water is fed in at the bottom of the tank and the " +
                    "hot water is drawn from the top." +
                    "\n" +
                    "Some water tanks might use multiple temperature probes to estimate the level of the hot water layer. " +
                    "A water heater with multiple temperature probes is likely to implement an algorithm to estimate the " +
                    "hot water tank percentage by taking into account the temperature values of each probe to determine " +
                    "the height of the hot water." +
                    "\n" +
                    "However it might be possible with a single temperature probe to estimate how much hot water is left " +
                    "using a simpler algorithm:" +
                    "\n" +
                    "> [!NOTE]" +
                    "\n" +
                    "> For example, if the target temperature was 60°C, the CurrentTemperature was 40°C from a single " +
                    "temperature probe measuring the average water temperature and the temperature of incoming cold " +
                    "water (COLD_WATER_TEMP) was assumed to be 20°C: TankPercentage = int(((current temperature - " +
                    "COLD_WATER_TEMP) / (target temperature - COLD_WATER_TEMP)) * 100) TankPercentage = min( " +
                    "max(TankPercentage,0), 100) TankPercentage = 50%"
            },

            {
                tag: "attribute", name: "BoostState", xref: "cluster§9.5.7.6",
                details: "Indicates whether the Boost, as triggered by a Boost command, is currently Active or Inactive." +
                    "\n" +
                    "See Section 9.5.8.1, \"Boost Command\" and Section 9.5.8.2, \"CancelBoost Command\" for more details."
            },

            {
                tag: "event", name: "BoostStarted", xref: "cluster§9.5.9.1",
                details: "This event shall be generated whenever a Boost command is accepted." +
                    "\n" +
                    "The corresponding structure fields within the WaterHeaterBoostInfoStruct are copied from the Boost " +
                    "command."
            },

            {
                tag: "event", name: "BoostEnded", xref: "cluster§9.5.9.2",
                details: "This event shall be generated whenever the BoostState transitions from Active to Inactive."
            },
            {
                tag: "command", name: "Boost", xref: "cluster§9.5.8.1",
                details: "Allows a client to request that the water heater is put into a Boost state."
            },

            {
                tag: "command", name: "CancelBoost", xref: "cluster§9.5.8.2",
                details: "Allows a client to cancel an ongoing Boost operation." +
                    "\n" +
                    "This command has no payload."
            },

            {
                tag: "datatype", name: "WaterHeaterHeatSourceBitmap", xref: "cluster§9.5.6.1",

                children: [
                    { tag: "field", name: "ImmersionElement1", description: "Immersion Heating Element 1" },
                    { tag: "field", name: "ImmersionElement2", description: "Immersion Heating Element 2" },
                    { tag: "field", name: "HeatPump", description: "Heat pump Heating" },
                    { tag: "field", name: "Boiler", description: "Boiler Heating (e.g. Gas or Oil)" },
                    { tag: "field", name: "Other", description: "Other Heating" }
                ]
            },

            {
                tag: "datatype", name: "BoostStateEnum", xref: "cluster§9.5.6.2",
                children: [
                    { tag: "field", name: "Inactive", description: "Boost is not currently active" },
                    { tag: "field", name: "Active", description: "Boost is currently active" }
                ]
            },

            {
                tag: "datatype", name: "WaterHeaterBoostInfoStruct", xref: "cluster§9.5.6.3",

                children: [
                    {
                        tag: "field", name: "Duration", xref: "cluster§9.5.6.3.1",
                        details: "This field shall indicate the time period, in seconds, for which the boost state is activated."
                    },

                    {
                        tag: "field", name: "OneShot", xref: "cluster§9.5.6.3.2",

                        details: "This field shall indicate whether the boost state shall be automatically canceled once the hot water " +
                            "has reached either:" +
                            "\n" +
                            "  - the set point temperature (from the thermostat cluster)" +
                            "\n" +
                            "  - the TemporarySetpoint temperature (if specified)" +
                            "\n" +
                            "  - the TargetPercentage (if specified)."
                    },

                    {
                        tag: "field", name: "EmergencyBoost", xref: "cluster§9.5.6.3.3",
                        details: "This field shall indicate that the consumer wants the water to be heated quickly. This may cause " +
                            "multiple heat sources to be activated (e.g. a heat pump and direct electric immersion heating " +
                            "element)." +
                            "\n" +
                            "The choice of which heat sources are activated is manufacturer specific."
                    },

                    {
                        tag: "field", name: "TemporarySetpoint", xref: "cluster§9.5.6.3.4",

                        details: "This field shall indicate the target temperature to which the water will be heated." +
                            "\n" +
                            "If included, it shall be used instead of the thermostat cluster set point temperature whilst the " +
                            "boost state is activated." +
                            "\n" +
                            "The value of this field shall be within the constraints of the MinHeatSetpointLimit and " +
                            "MaxHeatSetpointLimit attributes (inclusive), of the thermostat cluster."
                    },

                    {
                        tag: "field", name: "TargetPercentage", xref: "cluster§9.5.6.3.5",
                        details: "This field shall indicate the target percentage of hot water in the tank that the TankPercentage " +
                            "attribute must reach before the heating is switched off."
                    },

                    {
                        tag: "field", name: "TargetReheat", xref: "cluster§9.5.6.3.6",

                        details: "This field shall indicate the percentage to which the hot water in the tank shall be allowed to fall " +
                            "before again beginning to reheat it." +
                            "\n" +
                            "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%." +
                            "\n" +
                            "This field shall be less than or equal to the TargetPercentage field."
                    }
                ]
            }
        ]
    }
);
