Thanks to visit codestin.com
Credit goes to github.com

Skip to content

RFC: Suggestions for climate component refactoring #3910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from

Conversation

tinloaf
Copy link
Contributor

@tinloaf tinloaf commented Nov 6, 2017

Do not merge this! The changes are not yet implemented! This is a Request for Comments!

This is a suggestion for a refactoring of the climate component. I thought I'd outline this in form of documentation before starting the actual coding, to have a place for discussion how the new climate component looks like.

Most of this is taken from home-assistant/core#10151 (comment) . Some comments on the changed properties:

  • I tried to avoid name clashes between the "old" properties (that have been deprecated) and the new ones. My plan for implementation is this:
  1. Implement the new properties, increasing the size of the climate component. Additional, every climate object will have a "legacy" flag that determines whether the old (deprecated) or the new properties are in use. This requires no changes in the platforms aside from setting the legacy flag everywhere.
  2. Build a new-to-old translation where possible. E.g., setting heating as action will select heating as (deprectated) operation_mode. This should allow us to use some (many?) legacy platforms with the new interface.
  3. Wait for all platforms to implement the new interface, remove all deprecated properties and code.
  • The fan_mode and swing_mode properties still feel too platform-specific, but I'm not sure how to generalize this.

@MartinHjelmare
Copy link
Member

The source property will probably be very device specific. Do we need to standardize that or can we let the platforms define a list of available sources per entity?

Copy link
Member

@rytilahti rytilahti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just some generic thoughts. Is it already analyzed what types of different modes are to be supported in a generic manner? I think the proposal at hand is too broad, and has a good chance to confuse users and their automations, especially the properties whose implementation depends on values from other properties. Could this all be handled by simply providing a set of presets, which, where supported, should be provided by the platforms?

I would start thinking it from the direction of what types of functionality is to be exposed. This will also likely include introducing supported_features to the component, and defining a standard set, to give an idea, maybe features such as SUPPORTS_PRESETS, SUPPORTS_FAN_{SWING, MODE, PRESETS?}, SUPPORTS_COOLING, SUPPORTS_HEATING, SUPPORTS_HEATING_SOURCE_CONTROL, SUPPORTS_TEMPERATURE_CONTROL, and SUPPORTS_HUMIDITY_CONTROL could be defined?

* Off
* The **target_temperature** property selects the desired temperature for the device to achieve. The device will take measures to do so depending on what `action` is chosen. While most devices allow only to specify a `target_temperature` and will start heating / cooling when the temperature differs too far from that temperature, some devices allow finer control by specifying an acceptable temperature corridor:
* The **target_temp_high** property selects an upper limit on the acceptable temperature. The device will start cooling (if `cooling` or `auto` are selected as `action`) if that temperature is exceeded.
* The **target_temp_low** property selects a lower limit on the acceptable temperature. The device will start heating (if `heating` or `auto` are selected as `action`) if that temperature is exceeded.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest to avoid abbreviating to temp here to remain consistent with the target_temperature. I'm wondering though if this is not something to be implemented by the platforms themselves or be done with automations?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that some platforms allow to set a min / max temperature corridor, i.e. "start heating as soon as the temperature drops below target_temp_low, start cooling as soon as it exceeds target_temp_high". I would have to go through all the platforms though to verify this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I merely meant that the names should be target_temperature_high and target_temperature_low so that they are consistent with the "base attribute".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I would certainly do that, as well as renaming any "temperature" or "humidity" without a "current_" or "target_" into the respective one, to avoid all the confusion.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are multiple settings here:

  • min and max temperatures = used to avoid freezing or overheating by mistake
  • tolerance = most thermostats implement this around target_temperature
  • other targets = this is used as separate values for special modes (away, holiday, etc.)

I have to agree that min/max could be reused for away for example and use min for heating and max for cooling, however it really depends on the granularity that most users already use.

* The **source** property specifies (for devices which support this), what source to use for achieving the goal given in the `action`. Choices are:
* Electric
* Gas
* Fan_only
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned by @MartinHjelmare, this sounds too device-specific (if there is a need, how about allowing platforms to specify what types of "heating modes" they support?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds reasonable, I was trying to standardize as much as possible…

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As in the case of Generic Thermostat it really depends on the platform implemented. There might be the case that the component in home assistant will allow the ability for people to use a component that allows combining of a gas heater with an A/C unit under the same component and provide "auto" modes.

* The **target_humidity** property selects the target humidity. If this is set and the device is able to dry / humidify the air, it will do so if the actual humidity differs from this value.
* The **control** property specifies how the device is currently being controlled. Many devices allow to chose between an automated control (following a given preset, see below) or a manual control. *Note*: This does *not* influence whether the device is controlled by Home Assistant. The device is always controlled by Home Assistant, even if in `manual` mode. This property controls only the setting on the actual device. Choices are:
* Preset (device follows the device-specific preset, see below)
* Manual (the device itself is only controlled manually / via Home Assistant)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall the calls trying to control the device be just ignored by the component if this is set to preset, and leave it to be handled by the platform, i.e. allow only executing e.g. target temperature changes when this is set to manual? What is the expected outcome? What happens if a preset is "boost warming" but the action is "cooling"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. Personally I would think that as soon as e.g. set_temperature is called, the control property is changed to manual, i.e. presets are inactive from this point on. If the user calls set_temperature, he obviously wants the temperature not to be whatever the current preset says.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking about it, that's nonsense. Setting a temporary temperature until the next scheduled temperature change happens makes a lot of sense.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've seen this feature on Tado, where you can have some standard settings and the ability to diverge from those manually based on a condition (until manually moved back or until next automatic change comes into effect).

This would be a good feature to add, to allow comparison between presets and automation (in case the component allows it) and manual changes done to temperature through the UI.

* Gas
* Fan_only
* The **preset** property controls which preset to follow, if `preset` is selected for the `control` property. If the devices is in `manual` mode, this setting has no effect. The choices for this property are not standardized but differ from device to device. Note that the presets must be provided by the device, either statically or by direct configuration of the device. Home Assistant does not yet allow you to create / edit presets. If you want to emulate a preset, an automation and a timer component might be what you want.
* The **away** property can only be on or off and sets devices into a away-mode in which they usually conserve energy by heating / cooling less.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some devices support a specific away mode, but should this either be done with help of automations, or made more generic (considering that also other sorts of devices could benefit from it). eq3btsmart provides this currently through its operations list.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So… would "away mode" possible be a candidate for another option in the control property? Then it would be auto, manual and away, basically making away a special kind of auto.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that sounds fair, but I'm not sure if everyone agrees with it, and would prefer to let a separate service to handle that :-)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have auto, manual and away then you would rather have: home, sleep, away, vacation, manual.

This sounds like an attractive setting if you could publish metrics around it to graph it properly.

* The **preset** property controls which preset to follow, if `preset` is selected for the `control` property. If the devices is in `manual` mode, this setting has no effect. The choices for this property are not standardized but differ from device to device. Note that the presets must be provided by the device, either statically or by direct configuration of the device. Home Assistant does not yet allow you to create / edit presets. If you want to emulate a preset, an automation and a timer component might be what you want.
* The **away** property can only be on or off and sets devices into a away-mode in which they usually conserve energy by heating / cooling less.
* The **fan_mode** property selects between the different modes of the device's fan, if it has any. Choices differ from device to device.
* The **swing_mode** property selects whether and how the device should swing, if it supports this. Choices differ from device to device.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to provide a more generic interface to let platforms inform the component what kind of modes are supported?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean that platforms should be able to dynamically add properties? That would certainly be possible, but really go into the opposite direction than "standardize as much as possible", right? Also I think this would not be nice for the frontend…

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I was just thinking whether those are too specific for a broader "climate" device, but maybe it makes sense to expose "SUPPORTS_SWING_MODE" and "SUPPORTS_FAN_MODE" and leave them like proposed.

@rytilahti rytilahti changed the title Suggestions for refactoring WIP: Suggestions for climate component refactoring Nov 7, 2017
@tinloaf
Copy link
Contributor Author

tinloaf commented Nov 11, 2017

So, I'll try to list and order what I've read about this so far

So - how should I proceed? I'll admit that the approach of letting the platforms dynamically add properties sounds fancy, but that's probably going to be a mess in the front end, I guess.

@tinloaf tinloaf changed the title WIP: Suggestions for climate component refactoring RFC: Suggestions for climate component refactoring Nov 13, 2017
@tinloaf
Copy link
Contributor Author

tinloaf commented Nov 16, 2017

Thinking more about the action property, I think it's actually not useful to just have a list of discrete values. I think this is more of a collection of (independent) switches like supported_features. I think we should probably have four possible actions:

  • heat
  • cool
  • dry
  • humidify (is that a word?)

A climate device could then e.g. be in action mode HEAT | COOL | DRY, meaning that it would start heating, cooling or drying whenever the respective values are exceeded / undershot. If it was in action mode HEAT | DRY it would never cool, but still heat or dry, depending on what's necessary. Obviously we then also need a supported_actions flag.

@srirams
Copy link
Contributor

srirams commented Dec 2, 2017

Can we have some standardization over the difference between what something is set to and what it is currently doing. For example I can set the target temperature to 75, and the operating mode to heating, but the heater does not run 100% percent of the time, so should current_operation return what it is set to (heat) or what it is currently doing (heating, or idle). The current terminology seems to imply the latter (with terms like idle), but most components do the former and ignore the current operating state.

It is good to trace the operating state because filters need to be changed after a certain runtime, energy use can be estimated, etc.

@tinloaf
Copy link
Contributor Author

tinloaf commented Dec 2, 2017

I agree that it should be clear if some property reflects something "current" or something "intended". However, I think we should not double most of the modes. The "intended" mode is what we should be setting. If a platform can report on the "current" mode (e.g. whether it is currently actually heating or not) it should expose this via an attribute.

@@ -54,7 +87,7 @@ automation:

### {% linkable_title Service `climate.set_away_mode` %}

Set away mode for climate device. The away mode changes the target temperature permanently to a temperature
Set away mode for climate device. The away mode changes the target temperature permanently to a temperature
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion away mode should change the temperature, but should also restore it when removed to previously set value.


Additionally, there are a couple of deprecated properties that are still implemented by older platforms, but will gradually be replaced by the properties mentioned above:

* The **operation_mode** property (**deprecated**) is a mix of `action` and `control` above.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After looking through various implementation (some of which I find wrong), I think operation_mode makes sense.
operation_mode should be determined by the component and specify what types of function could your "climate" component perform.

Some climate devices can do only heating, some can do only cooling, some can do both, some can do both and switch automatically between them, and some should have "off" which would ignore any other commands.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's why I suggest the action property. It's basically just a change in name (and some semantics) for two reasons:

  • To make clear what the property is used for (I think 'action' is a more clear wording than 'operation_mode'). While "economy" might be an operation_mode, it should be pretty clear that "economy" is not an action (but rather a preset).
  • To have a clear separation between the old set of attributes and the new set of attributes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have to agree, that a change would allow for easier refactoring. Also I really like the "preset" idea. That would move people away from hacking operation_modes and fiddling in weird ways with "hold" modes.


We explain each of the properties and the possible choices for them shortly:

* The **action** property specifies the overall operational mode that the device is currently in. Choices are:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what in my opinion should have been the options for operation_mode. I would rather fix that instead of adding a new one.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not talking about adding. I'm talking about replacing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think Operation expresses better than Action the types here. But that is my personal view and preference of course.


* The **operation_mode** property (**deprecated**) is a mix of `action` and `control` above.
* The **aux_heat** property (**deprecated**) turns auxiliary heating on or off and is controlled via `action` in newer devices.
* The **hold_mode** property (**deprecated**) handles different choices for possible `target_temperature`s and is handled via the `preset` property for newer devices.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This I have to agree that is confusing, especially as many platform mixed this with operation_mode and created even more confusion. Presets do sound like a better choice.

@ciotlosm
Copy link
Contributor

Too bad I only see this PR now. I looked at generic_thermostat and I tried to improve it and it was indeed a lot of freedom of implementation that created confusion and allowed for some bugs.
If it helps, please have a look at: home-assistant/core#11325

@KlaasH
Copy link
Contributor

KlaasH commented Mar 2, 2018

Has this been superseded by something, or is it still a live issue that hasn't moved lately, or is it dead?

My main concern in this discussion is that there's no mention of any capability around reporting the actual current action of the thermostat--i.e. whether it's calling for heat, calling for cooling, etc. The Ecobee component, at least, captures this in the "operation" attribute (which is pretty confusing, but as is clear from this discussion, it's hard to make clear names and distinctions around this stuff). I don't know how many thermostats can do it, but I would guess at least some others would be capable of exposing that information, even if the components currently don't.

Besides target temperature, when/how much the system is actually running is the piece of data I'm most interested in from my thermostat. Among other things, it serves as a pretty good proxy for energy consumption.

In light of this, I don't love "action" as the term for whether the thermostat is set to maintain a minimum temp, maximum temp, or range (i.e. heat, cool, or auto.)
When my thermostat is set to heat but the temperature is above the set point, i.e. it's maintaining a minimum temperature but is currently idle, I wouldn't describe what it's doing as "action: heating". To me that seems more like a mode (i.e. "temperature_mode: heat"). That would make "temperature_action" available to describe the "calling for X" vs "idle" distinction, though it's possible something else along the lines of "operation_status" or "current_action" would serve better.

@stale
Copy link

stale bot commented May 1, 2018

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

@stale stale bot added the Stale The PR had no activity for quite some time, and is marked as Stale label May 1, 2018
@tinloaf
Copy link
Contributor Author

tinloaf commented May 3, 2018

This is very much superseded by home-assistant/architecture#22 anyways. :)

@tinloaf tinloaf closed this May 3, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Stale The PR had no activity for quite some time, and is marked as Stale
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants