New Entity Proposal: Boiler

[zxdavb]

I am in the process of adding a new CH/HW (central heating / hot water) component. I see that there is no boiler class & @balloob has previously suggested one. With thanks to ideas in another issue herein, I suggest the following as a starting point for discussion...

In my mind, a boiler can be heated by various sources (an electrical element(s), or from (say) a combi/district boiler, via a coil).

A cylinder is a container for HW, filled with (either) cold water, which is heated used one of the two previous methods, or filled with hot water from (say) a combi/district boiler. Cylinders may have an internal 'cylinder stat' which will stop the boilers from exceeding some maximum temperature - this may not be part of the boiler.

icon = "mdi:thermometer-lines"
supported_features = SUPPORT_OPERATION_MODE | SUPPORT_ON_OFF | support_temperature | support_target_temp
state: [
  STATE_OFF,  # boiler not active (not using energy), current temp is irrelevant
  STATE_ON,  # boiler will act to attain/maintain target temp
]

state_attributes: [
  'operation_mode': [manual, schedule, etc]
  'current_temperature', # reported by a temperature sensor
  'target_temperature', # the temperature to reach...
  'temperature_unit',  # TEMP_CELSIUS, or the other one...
  'min_temperature',  # lowest possible target temp
  'max_temperature',  # maximum possible target temp
  'precision',  #  1, 0.5 or 0.1 (PRECISION_WHOLE, HALVES, TENTHS)
]

Services: [  # some devices allow setting these parameters ahead of time
  'set_operation_mode':  { 'service_data': ['operation_mode'] }
  'set_temperature': { 'service_data': ['target_temperature'] }
  'turn_off',
  'turn_on': {}
]

[zxdavb]

[ I will try to keep this comment up to date ]

Current consensus (such as it is) seems to include:

Name Suggestions include water_heater and boiler.

Description Stored potable water heated by a system, +/- backup systems. For example main system is district boiler, or solar panels, backup system is electrical immersion heaters.

State At a minimum, two possible states: STATE_OFF, STATE_ON and, optionally: STATE_HEATING. Some systems will report Off/On only, other may do Off/On (but idle)/Heating.

STATE_OFF means off (current_temp will have no effect on its behaviour), and otherwise it is on/heating (the boiler will do something if current_temp drops below target_temp).

Of course, we still have STATE_UNKNOWN for error states, etc.

Temperatures Obviously, the stored water will have a current_temperature, and and target_temperature. In the case of a heat exchanger coil, the HW in that coil will also have its own temperature (supply_temperature?).

[elupus]

Curius how this turns out. I'm author of a nibe heat pump custom component. At the moment I'm pretty much spraying sensor entities, but that is quite messy.

[zxdavb]

@elupus Yeah, me too - I'm waiting for others to contribute!

I was thinking about state. The boiler could be STATE_OFF (not doing anything to raise current_temp to target_temp), or STATE_ON (reading current_temp, and if below that, doing something to raise it to target_temp).

If the boiler is STATE_ON, should we have the option of saying it is STATE_ON_AND_HEATING (or just STATE_ACTIVE/STATE_HEATING), and STATE_ON_BUT_IDLE (or just STATE_IDLE)?

My preference is for just three states: STATE_OFF, STATE_ON, and STATE_HEATING (or STATE_ACTIVE). STATE_OFF means off, and otherwise it is on (and some boilers will be able to says if actively heating).

Of course, we still need STATE_UNKNOWN for error states, etc.

[tsvi]

I think HEATING and IDLE are the correct names as ON_AND_HEATING would imply you could have OFF_AND_HEATING???

On Tue, Sep 4, 2018, 21:39 zxdavb notifications@github.com wrote:

I was thinking about state. The boiler could be OFF (not doing anything to raise current_temp to target_temp), or ON (reading current_temp, and if below that, doing something to raise it to target_temp).

If the boiler is ON, should we have the option of saying it is ON_AND_HEATING (or just HEATING), and ON_BUT_IDLE (or just IDLE)?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/home-assistant/architecture/issues/59#issuecomment-418474590, or mute the thread https://github.com/notifications/unsubscribe-auth/ABTZcLDKbrLA1uySSPIV1Jz2PdyrTIsVks5uXsj4gaJpZM4WAs0L .

[zxdavb]

I agree - OFF & ON, or OFF, IDLE & ACTIVE it is!

[dgomes]

I think boiler is not generic enough.

E.g. I have solar panels for water heating, with state and information much similar to the boiler use-case.

HVAC is too generic (it includes more things besides hot water), but DHW (Domestic Hot Water) is the general term used by manufactures.

[zxdavb]

Do we agree the basic use-case is for stored water to be heated by some system? That would include all 3 means mentioned thus far: 1) electrical element (from mains, PV cells), 2) HW coil (system boiler, district HW, solar panels), and 3) gas-fired.

When you say "boiler is not generic enough", do you mean the name of the entity class? I think DHW doesn't offer enough advantage as a name, e.g. the HW may not be domestic (although we caould ignore that point, I think) - 'domestic-hot-water', or 'domestic-hw'?.

The term 'boiler' is short & sweet: most people would understand 'boiler', even though the water never boils (I understand 50-60C is about right, with 61-62C used to kill any resident pseudomonas bugs).

I am from the UK, and I think the term here would be 'cylinder', since most people have a (tankless) combi boiler, which produces HW on demand.

In the US, I think 'boiler' is the term, and I happen to know that some in some countries it's called a 'geyser'.

[elupus]

Do you include hot water used for floor heating and radiators in that definition?

[zxdavb]

No, I wouldn't - that will come under climate - even if the HW for the radiators, and the HW for the heat exchanger in the boiler are coming from the same source!

I am making an assumption here - I am limiting my thoughts to stored hot water / DHW. I feel it would open a can of worms to include thing like a combi boiler (a tankless supply of HW), or a system boiler (which supplies HW for a heat exchanger coil in a cylinder).

I have a fancy system boiler that can supply info like: is the fan running (%), the water pressure in the CH circuit, what mode it is in (e.g. igniting, running on), etc. Maybe these things could be device_state_attributes?

So, for @dgomes , any specifics of the solar panels themselves may not be within the realms of this proposed entity, although I think it would be reasonable to track: state (as above), mode, and supply_temp.

[dgomes]

My 'cylinder' is heated by my solar panels and by a Heat Pump as a backup (when the desired temperature is not reach due to lack of sun).

DHW is more encompassing, or just hot-water and therefore include other systems such as central heating.

My solar panels just provides states (ON/OFF - circulation pump that transfers heat from the panels to the cylinder) and temperatures (panel temperature + cylinder temperature).

I think temperatures + status should cover most use cases and have leave other aspects to specific components.

[zxdavb]

@dgomes I guess the question is: is this component the source of heat for the cylinder, or is it the cylinder itself? My preference is the latter, because a cylinder can have multiple sources of heat (mine has a backup electrical heater).

I think hot-water is not quite right - stored-hot-water would be better, or stored-dhw? I'd still vote for boiler, tho'. If we can't agree on this, no bother - let's kick it into the grass for now, and until others can view their opinion on it.

Similar to yours, my main heat source (a system boiler that provides HW to the heat exchanger in the cylinder) can track delivered_temp, and return_temp (the difference mostly being transferred to the HW in the cylinder).

We could add heat_source (main_heat_source, backup_heat_source, current_heat_source) as a state_attribute? And something like cutout_temp (the temp beyond which the cylinder will send a signal back to the heat source saying to stop)?

[dgomes]

I think it would be most useful to have the combined system, even if not every system can provide all the information.

I'm think along the lines of the weather platform.

Let's agree on stuff:

State:

• [ ] HEATING: heat is being transferred to the system (MANDATORY)
• [ ] IDLE: no heat is being transferred but the system controller is live (MANDATORY)
• [ ] OFF: no heat is being transferred and the system controller if off

Attributes:

• [ ] current_temp: reservoir temperature (MANDATORY)
• [ ] delivered_temp: temperature supplied to the reservoir
• [ ] return_temp: temperature at the exit of the reservoir

[awarecan]

"Water Heater" seems more common term used in US, if you don't include "floor heating and radiators in that definition"

More precisely, water heater and boiler are regulated by different code, Uniform Plumbing Code vs Uniform Mechanical Code.

A water-heating device that exceeds any one of the following should be classified as a water boiler:

• 120 gallons (454.2 liters) nominal water storage capacity;
• 160 psi (1103.2 kPa) operating pressure;
• 210 degrees Fahrenheit (99 degrees Celsius) operating temperature; or
• 200,000 Btu/hr. (58,620 kW) heat input.

Reference: When does a water heater become a boiler?

[zxdavb]

Agreed - I think include target_temp (when it will switch from STATE_HEATING to STATE_IDLE)?

And OK to have STATE_ON for those systems that cannot report if STATE_HEATING vs STATE_IDLE? My experience is most boilers will tell you if they're on or off, but many wont tell you if they're on/heating, or on/idle.

[zxdavb]

FWIW: My 300L cylinder has two safety systems - one is configurable, the other is a hard wired absolute upper limit of: 90C (194F) and 10bar (1000kPa), its usual maximum is 85C/8bar, but usually 55-65C and 3.5bar.

It has 6kW via electrical immersion heaters (takes ~3h to heat up from room temp), and approx 1/3x that via the coil.

So it's a water heater, then!

[dgomes]

Mine would also be a water-heater ;)

If you can't report HEATING you just stick to ON/OFF

[zxdavb]

OK, lets go with Off/On/Heating - I've updated post 2. Keep an eye on it, and let me know if I'm going off track.

[zxdavb]

Do we want to track the supply type? SUPPLY_SYSTEM_BOILER, SUPPLY_DISTRICT_BOILER, SUPPLY_SOLAR_PANELS, SUPPLY_IMMERSION_HEATER, or SUPPLY_PRIMARY, SUPPLY_BACKUP?

[dgomes]

we should use device_class as in other platforms :)

[balloob]

water heater has been added as a component