Add new DEFROST state to HVACAction

[KazWolfe]

Context

I am currently working on an ESPHome integration for a heat pump which supports automated defrosting. At present, the only ways to report that the heat pump is in defrost mode is through the use of the PREHEATING HVACAction (as done by the MelCloud integration) or via a sensor (e.g. as done by Vallox's integration or the Haier ESPHome integration).

Many heat pumps on the market support some kind of "defrost" mode, where the system will run in reverse for a few minutes to melt any accumulated ice and keep the system performing in colder environments. I believe that denoting this state on its own is valid - it explains why the system is not currently generating heat, and it reflects the run cycle of modern heat pump systems. While the use of preheating likely can be a solution, preheating is its own state as well (and, strictly speaking, is not semantically accurate to what the climate unit is doing at that point in time).

As a side benefit, other core integrations like tessie and teslemetry both also note and track a defrost mode. While this is semantically slightly different as the intent is to denote that a car is currently being defrosted, this would also be a valid use of this HVACAction. Whether defrost should also be listed as a mode for cases like this is out of scope for this proposal.

Proposal

Similar to what was done for the preheating architectural decision, this would require the following changes:

• Add a new defrost entry to the HVACAction enum in core and relevant UI elements.
• Optionally update existing integrations for systems like MelCloud and Vallox.

Consequences

This change will increase verbosity of certain climate cards for supported units. The use of defrost may also be resolved through the use of preheat, though as discussed above this appears to lack sufficient differentiation in context.

Alternate solutions would include:

• The ability to put custom elements on climate cards (e.g. any sensor text, may be useful for error messaging as well).
• A custom action string field, though this likely is undesirable as it creates unnecessary complexity.
• Expanding documentation to denote that "preheating" should cover any related state, though this would block the Tesla use case noted above.

[frenck]

Thanks for the architectural proposal @KazWolfe 👋

As part of our decision-making, we'd like to know which integrations can benefit from this (besides generic purpose integrations like ESPHome, templates, or MQTT). We generally don't want to change or models based on a single integration.

Can you please provide research on the common use of this proposal?

You did. Thanks 👍

Sounds reasonable to me. I'd like to see another approval from another Core member before accepting it.

../Frenck

[KazWolfe]

Sure thing. Within the Home Assistant codebase proper, the only climate entity that could make use of this would be the MELCloud integration. At present, it transforms an incoming defrost state to HVACAction.PREHEATING in lieu of exposing that additional information elsewhere.

That being said, there is additional art for similar things within the HA codebase as well:

• Vallox exposes defrost state information in a sensor as part of heatpump logic. This isn't particularly useful for the climate context, but it does show that this is a relatively common thing.
• The aforementioned Tesla integrations would use defrost in a more novel way (though it is debatable if it would be better suited as a mode).

If you're accepting things from custom components as well:

• A xiaomi custom component exposes defrost state as an attribute on a climate entity.
• A luxtronic custom component uses similar, mapping it to Idle
• A kumo/MEHBAC custom component also maps defrost state to an attribute.

The general case, I believe, would honestly primarily be focused towards more general-purpose integrations - ESPHome, modbus entities, BACnet specifications and similar would benefit the most from this as relatively few heat pumps seem to currently have their own native Home Assistant integrations (likely due to the rather closed nature of modern hardware - most people integrating things beyond “public” states would likely be using ESPHome or similar anyways).

[gjohansson-ST]

👍 from me. I think this makes sense as an action for heat pumps.

[Sammy1Am]

Looks like a lot of integrations got listed already, but figured I would pile on with a +1 for this being useful, and throw in some additional integrations that are similarly tracking defrost state, but unable to surface it as a climate action currently:

AUX AC
Aquarea
Lennox

[PeteRager]

I like it. I don't think it's an hvac_action

The current HVAC action indicates what the hvac system is trying to do - heating, cooling, dehumidifying, etc. When an hvac system is defrosting this is because it is cooling and the controller has detected frost building up so it turns a heater on. So it's not a new hvac action as the system is still "cooling", it is however an attribute or status on the equipment operation.

Energy analysis is typically done by pivoting the power usage by the hvac action. So you can see power used for heating, cooling, etc. Adding defrost in would then allocate some power usage to this new action, but really it's just power used for cooling. As more controller data is brought in to HA, there will be many equipment statuses - Smooth Setback Recovery, HRV ventilation State, Heat coast. Just like when a hot water furnace is heating - the burner is not always on - I don't think we'd propose subdividing hearing into "heating" and "burner on" - as those are internal details of the equipment.

Having the information available is helpful. I have folks controlling the CFM of the Lennox system to avoid needing to defrost as that's wasted power. So, let's model it.

Part of the overloading issue is the climate entity is modeling a thermostat. A modern hvac system has many components. Furnace, Blower, Zoning Dampers, Heat Pump. That should not try to be modeled in the climate entity. Today these can be modeled by adding devices for each of those component and sensors to the devices. But there is no standardization. Perhaps we start by modeling hvac equipment?

screen shots from the Lennox integration

[KazWolfe]

I'm kind of torn on "it's not really an action", since I'm following in the footsteps of preheating (which also would not really qualify as an action by this logic). One one hand, yes, it is just an internal state issue, but on another, it does explain to the user why the system is currently not blowing out hot air and so should (IMO) be easily accessible/visible to the user. This is especially important for the all-essential WAF - if the heater isn't blowing hot air, you shouldn't have to hunt through a complex dashboard with dozens of components to find the one that's saying what's going on.

IMO everything about "what is the device intending to do" is best tracked by the Mode (since that's what the user requested), and then Action can remain what it's actually doing with some extra state information for the more interesting reports.

But this also does bring up a good point re overloading - a Defrosting action would also make sense on, say, a refrigerator using the climate card to set its internal temperature. I don't think this is necessarily a valid use of the climate entity, but it is a sensible one. Modeling HVAC systems as their own thing makes sense in a way, but there's just as much variability to how they work (especially with mini-splits) that I'm not certain an all-in-one solution is reasonable.

[Sammy1Am]

I definitely think it's reasonable to keep HVACActions limited to what the system is actually doing, so like you said, having multiple heating stages (e.g. burner on/off), etc. as actions doesn't make sense. However, I would argue that including DEFROSTING specifically makes sense because:

• PREHEATING is already an HVACAction. Preheating isn't an option on a thermostat, and isn't something the user requests; but importantly when the system is preheating it's not doing what the user has requested (HEATING), and so it's helpful to show the user that the system is doing something other than (but related to) what they've requested.
• Similarly when a heat pump is defrosting, it's not doing the requested action (HEATING), it's performing a different action.
• If users are looking to compare graphs of sensors like temperature to HVACAction, having the action showing defrost during dips/flat spots in temperature would help those correlate.
• Your point about energy consumption is not something I had considered, and is an excellent point. However I think an argument could be made that separating energy used for preheating and defrosting could be informative as it would separate out the additional energy used by the system during especially cold weather.

Separately I think you could make the same argument against including PREHEATING, and so maybe the correct solution is to remove PREHEATING and DEFROSTING to their own separate home. However I would argue that IDLE also qualifies as an action separate from what the system has been requested to do (i.e. the user can't set the system to IDLE, but while set to COOL it can be performing IDLE because of conditions like the setpoint being met), but I think removing IDLE would be confusing.

---

Edit: Potentially relevant line from the docs:

The HVAC action describes the current action. This is different from the mode, because if a device is set to heat, and the target temperature is already achieved, the device will not be actively heating anymore.

[PeteRager]

You both make excellent points.

keep HVACActions limited to what the system is actually doing

That means we could also differentiate to the user that the heat pump is locked out and the gas furnace is running? On the Lennox Panel it would display heating and then a lock out indicator.

it does explain to the user why the system is currently not blowing out hot air

This makes a ton of sense. You need that info.

So we could add defrost to hvac action and then using the same criteria add the heat pump lockout actions and the "heat coast" (this is when the heat turns off before the setpoint is reached because it knows that it's going to "coast" to the setpoint in a few minutes), or "heating+humidifying", "waiting to dry" (Lennox announces this when humidity to high but the inside temperature is too low'. Point is there's a dozen or two of these actions to explain what the system is doing or not doing. This is path we could continue on.

Alternatively, we could look at a small set of hvac actions and a "sub status" field (need a better name), which would contain more detailed info, like defrost, heat pump lockout, coasting, waiting to dehumidify, etc.

Examples:

Cooling / Cooling
Cooling / Defrost
Cooling / Coasting
Heating / Preheating
Heating / Heat Pump Lockout
Heating / Coasting
Idle / Waiting to dehumidify

[Sammy1Am]

That means we could also differentiate to the user that the heat pump is locked out and the gas furnace is running?

I think this would be useful, yes (though in that specific scenario we could maybe encapsulate it in something slightly more generic like "backup heat" or "aux heat"). Coasting sounds a lot like idle at first, but might actually involve a different fan speed than true idle, so I think that's useful as well.

Alternatively, we could look at a small set of hvac actions and a "sub status" field [...]

In the examples, I don't see how the "primary"/left-side action is any different than the already-existing mode value. Mode/Action already covers:

Heat/Preheating
Heat/Heating
Heat/Idle

It seems unnecessary to expand them to:

Heat/Heating/Preheating
etc.

That is to say, my understanding is that HVACAction is already supposed to be the more detailed info field to pair with the primary-goal Mode field.

Edit: I do understand this starts to open the door to much longer list of potential actions; but I think PREHEATING already started that process, and to limit actions only to the same values as MODE somewhat defeats the purpose of the second field.

[PeteRager]

Great points. I've laid out a couple of approaches in tables to give us something concrete to look at. I've added a couple of additional states in parenthesis - not suggesting we add those; just to illustrate what it could look like as we add more states.

This is the current proposal and the simplest thing to do as it builds off of the preheating decision

hvac_mode	hvac_action
off	off
heat	idle
	heating
	preheating
	defrosting
	(coast)
cool	idle
	cooling
	(precooling)
	(coast)
heat cool	idle
	heating
	preheating
	defrosting
	cooling
	(precooling)
	(coast)
dry	idle
	drying
fan_only	idle
	fan

This is an alternate way to look at it with third level of structure, which would make the energy analysis pivots come out very easily (e.g. how much energy is spent heating, and then the drill down into cooling to see how much is spent in preheating and defrosting)

hvac_mode	hvac_action	status (need better term)
off	off	-
heat	idle	-
	heating	-
		preheating
		defrosting
		(coast)
cool	idle	-
	cooling	-
		(precooling)
		(coast)
heat cool	idle
	heating	-
		preheating
		defrosting
		(coast)
	cooling	-
		(precooling)
		(coast)
dry	idle
	drying
fan_only	idle
	fan