Skip to content
This repository has been archived by the owner on Mar 19, 2024. It is now read-only.

Commit

Permalink
feat: Climate presets
Browse files Browse the repository at this point in the history
  • Loading branch information
@thomasgermain
thomasgermain committed Dec 16, 2023
1 parent 5a180da commit f62970e
Show file tree
Hide file tree
Showing 11 changed files with 521 additions and 364 deletions.
151 changes: 104 additions & 47 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,51 +10,67 @@ Ideas are welcome ! Don't hesitate to create issue to suggest something, it will
**This integration is also compatible with sensoAPP and has been tested with the vr920 and vr921 devices.**

## Installations

- Through HACS [custom repositories](https://hacs.xyz/docs/faq/custom_repositories/) !
- Otherwise, download the zip from the latest release and copy `multimatic` folder and put it inside your `custom_components` folder.
- Otherwise, download the zip from the latest release and copy `multimatic` folder and put it inside
your `custom_components` folder.

You can configure it through the UI using integration.
You have to provide your username and password (same as multimatic or senso app), if you have multiple serial numbers, you can choose for which number serial number you want the integration.
You have to provide your username and password (same as multimatic or senso app), if you have multiple serial numbers,
you can choose for which number serial number you want the integration.
You can create multiple instance of the integration with different serial number (**This is still a beta feature**).

**It is strongly recommended using a dedicated user for HA**, for 2 reasons:

- As usual for security reason, if your HA got compromised somehow, you know which user to block
- I cannot confirm it, but it seems multimatic and senso API only accept the same user to be connected at the same time

## Changelog

See [releases details](https://github.com/thomasgermain/vaillant-component/releases)

## Provided entities

- 1 water_heater entity, if any water heater: `water_heater.<water heater id>`, basically `water_heater.control_dhw`
- 1 climate entity per zone (expect if the zone is controlled by room) `climate.<zone id>`
- 1 climate entity per room `climate.<room name>`
- 1 fan entity `fan.<ventilation_id>`
- 1 fan entity `fan.<ventilation_id>`
- 1 binary_sensor entity `binary_sensor.control_dhw` reflecting if the circulation is on or off
- 1 binary_sensor entity `climate.<room name>_window` per room reflecting the state of the "open window" in a room (this is a feature of the multimatic API, if the temperature is going down pretty fast, the API assumes there is an open window and heating stops)
- 1 binary_sensor entity `climate.<room name>_window` per room reflecting the state of the "open window" in a room (this
is a feature of the multimatic API, if the temperature is going down pretty fast, the API assumes there is an open
window and heating stops)
- 1 binary_sensor entity `climate.<sgtin>_lock`per device reflecting if valves are "child locked" or not
- 1 binary_sensor entity `binary_sensor.<sgtin>_battery` reflecting battery level for each device (VR50, VR51) in the system
- 1 binary_sensor entity `binary_sensor.<sgtin>_battery` reflecting connectivity for each device (VR50, VR51) in the system
- 1 binary_sensor entity `binary_sensor.<sgtin>_battery` reflecting battery level for each device (VR50, VR51) in the
system
- 1 binary_sensor entity `binary_sensor.<sgtin>_battery` reflecting connectivity for each device (VR50, VR51) in the
system
- 1 binary_sensor entity `binary_sensor.multimtic_system_update`to know if there is an update pending
- 1 binary_sensor entity `binary_sensor.multimtic_system_online` to know if the vr900/920 is connected to the internet
- 1 binary_sensor entity `binary_sensor.<boiler model>` to know if there is an error at the boiler. **Some boiler does not provide this information, so entity won't be available.**
- 1 binary_sensor entity `binary_sensor.<boiler model>` to know if there is an error at the boiler. **Some boiler does
not provide this information, so entity won't be available.**
- 1 temperature sensor `sensor.outdoor_temperature` for outdoor temperature
- 1 sensor for each report in live_report (boiler temperature, boiler water pressure, etc.)
- 1 binary sensor `binary_sensor.multimtic_quick_mode` to know a quick mode is running on
- 1 binary sensor ` binary_sensor.multimtic_holiday` to know the holiday mode is on/off
- 1 binary sensor `binary_sensor.multimatic_errors`indicating if there are errors coming from the API (if `on`, details are in `state_attributes`)
- 1 binary sensor `binary_sensor.multimatic_errors`indicating if there are errors coming from the API (if `on`, details
are in `state_attributes`)

## Provided devices

- 1 device per VR50 or VR51
- 1 device for the boiler (if supported). Some boilers don't provide enough information to be able to create a device in HA.
- 1 device for the boiler (if supported). Some boilers don't provide enough information to be able to create a device in
HA.
- 1 device for the gateway (like VR920)
- 1 "multimatic" (VRC700) device (the water pressure is linked to the VRC 700 inside the multimatic API)
- hot water circuit
- heating circuit

For the climate and water heater entities, you can also find

For the climate and water heater entities, you can also find
- the 'real multimatic mode' running on (AUTO, MANUAL, DAY, etc)

For the boiler error entity, you can also find
For the boiler error entity, you can also find

- the last update (this is not the last HA update, this is the last time multimatic checks the boiler)
- the status code (these can be found in your documentation)
- the title (human-readable description of the status code)
Expand All @@ -63,56 +79,97 @@ For the `binary_sensor.multimtic_quick_mode`, when on, you have the current quic
For the `binary_sensor.multimtic_holiday`, when on, you have the start date, end date and target temperature

## Provided services

- `multimatic.set_holiday_mode` to set the holiday mode (see services in HA ui to get the params)
- `multimatic.remove_holiday_mode` .. I guess you get it
- `multimatic.set_quick_mode` to set a quick mode
- `multimatic.remove_quick_mode` don't tell me you don't get it
- `multimatic.remove_quick_mode` don't tell me you don't get it
- `multimatic.set_quick_veto` to set a quick veto for a climate entity
- `multimatic.remove_quick_veto` to remove a quick veto for a climate entity
- `multimatic.request_hvac_update` to tell multimatic API to fetch data from your installation and made them available in the API
- `multimatic.request_hvac_update` to tell multimatic API to fetch data from your installation and made them available
in the API
- `multimatic.set_ventilation_day_level` to set ventilation day level
- `multimatic.set_ventilation_night_level` to set ventilation night level
- `multimatic.set_datetime` to set the current date time of the system

This will allow you to create some buttons in UI to activate/deactivate quick mode or holiday mode with a single click


## Expected behavior

On **room** climate:
### Room climate

#### Changing temperature

Changing temperature while ...
- `MANUAL` mode -> it simply changes target temperature
- other modes -> it creates a quick_veto (duration = 3 hours) (it's also removing holiday or quick mode)

Modes mapping:
- `AUTO` -> `HVAC_MODE_AUTO` & `PRESET_COMFORT`
- `OFF` -> `HVAC_MODE_OFF` & no preset
- `QUICK_VETO` -> hvac depends on state & `PRESET_QUICK_VETO` (custom)
- `QM_SYSTEM_OFF` -> `HVAC_MODE_OFF` & `PRESET_SYSTEM_OFF` (custom)
- `HOLIDAY` -> `HVAC_MODE_OFF` & `PRESET_HOLIDAY` (custom)
- `MANUAL` -> no hvac & `PRESET_MANUAL` (custom)

On **zone** climate:
- Changing temperature will lead to a quick veto with selected temperature for 6 hours (quick veto duration is not configurable for a zone)

Modes mapping:

| Vaillant Mode | HA Mode |
| ------------- |-----------------------------------------------------|
| AUTO | `HVAC_MODE_AUTO` & `PRESET_COMFORT` |
| DAY | no hvac & `PRESET_DAY` (custom) |
| NIGHT | no hvac & `PRESET_SLEEP` |
| OFF | `HVAC_MODE_OFF` & no preset |
| ON (= cooling ON) | no hvac & `PRESET_COOLING_ON` (custom) |
| QUICK_VETO | depends on the state & `PRESET_QUICK_VETO` (custom) |
| QM_ONE_DAY_AT_HOME | HVAC_MODE_AUTO & `PRESET_HOME` |
| QM_PARTY | no hvac & `PRESET_PARTY` (custom) |
| QM_VENTILATION_BOOST | `HVAC_MODE_FAN_ONLY` & no preset |
| QM_ONE_DAY_AWAY | `HVAC_MODE_OFF` & `PRESET_AWAY` |
| QM_SYSTEM_OFF | `HVAC_MODE_OFF` & `PRESET_SYSTEM_OFF` (custom) |
| HOLIDAY | `HVAC_MODE_OFF` & `PRESET_HOLIDAY` (custom) |
| QM_COOLING_FOR_X_DAYS | no hvac & `PRESET_COOLING_FOR_X_DAYS` |
- other modes -> it creates a quick_veto (duration = 3 hours) and it removes holiday or quick mode.

#### Modes mapping

| Multimatic mode | HA HVAC | HA preset |
|-------------------------|---------|----------------------------|
| AUTO | AUTO | COMFORT |
| OFF | OFF | / |
| QUICK_VETO | HEAT | PRESET_QUICK_VETO (custom) |
| SYSTEM_OFF (quick mode) | OFF | PRESET_SYSTEM_OFF (custom) |
| HOLIDAY (quick mode) | OFF | PRESET_AWAY |
| MANUAL | HEAT | PRESET_HOME |

#### Available HVAC mode

| HVAC mode | Multimatic mode |
|-----------|-----------------|
| AUTO | AUTO |
| OFF | OFF |

#### Available preset mode

| preset mode | Multimatic mode |
|----------------|-----------------|
| PRESET_COMFORT | AUTO |
| PRESET_HOME | MANUAL |

### Zone climate

#### Changing temperature

Changing temperature will lead to a quick veto with selected temperature for 6 hours (quick veto duration is not
configurable for a zone)

#### Modes mapping

| Vaillant Mode | HA HVAC | HA preset |
|---------------------------------|------------------------|----------------------------|
| AUTO / TIMED CONTROLLED | AUTO | PRESET_COMFORT |
| DAY | HEAT | PRESET_HOME |
| NIGHT | OFF | PRESET_SLEEP |
| MANUAL | Based on zone function | / |
| OFF | OFF | / |
| ON | Based on zone function | / |
| QUICK_VETO | HEAT | PRESET_QUICK_VETO (custom) |
| ONE_DAY_AT_HOME (quick mode) | AUTO | PRESET_HOME |
| PARTY (quick mode) | OFF | PRESET_HOME |
| VENTILATION_BOOST (quick mode) | FAN_ONLY | / |
| ONE_DAY_AWAY (quick mode) | OFF | PRESET_AWAY |
| SYSTEM_OFF (quick mode) | OFF | PRESET_SYSTEM_OFF (custom) |
| HOLIDAY (quick mode) | OFF | PRESET_AWAY |
| COOLING_FOR_X_DAYS (quick mode) | COOL | / |

#### Available HVAC mode

| HVAC mode | Multimatic mode |
|-----------|---------------------------------|
| AUTO | AUTO |
| OFF | OFF |
| FAN_ONLY | VENTILATION_BOOST (quick mode) |
| COOL | COOLING_FOR_X_DAYS (quick mode) |

#### Available preset mode

| preset mode | Multimatic mode |
|----------------|------------------------------|
| PRESET_COMFORT | AUTO |
| PRESET_HOME | ONE_DAY_AT_HOME (quick mode) |
| PRESET_AWAY | ONE_DAY_AWWAY (quick mode) |

### DHW climate

Expand All @@ -125,7 +182,7 @@ Modes mapping:
| SYSTEM_OFF (quick mode) | OFF | PRESET_SYSTEM_OFF |
| HOTWATER_BOOST (quick mode) | HEAT | PRESET_BOOST |
| PARTY (quick mode) | OFF | PRESET_HOME |
| ON | HEAT | PRESET_NONE |
| ON | EAT | PRESET_NONE |

#### Available HVAC mode

Expand Down
25 changes: 24 additions & 1 deletion custom_components/multimatic/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,17 @@
import logging

from pymultimatic.api import ApiError, defaults
import voluptuous as vol

from homeassistant.config_entries import ConfigEntry
from homeassistant.const import CONF_SCAN_INTERVAL, EVENT_HOMEASSISTANT_STOP
from homeassistant.const import (
CONF_PASSWORD,
CONF_SCAN_INTERVAL,
CONF_USERNAME,
EVENT_HOMEASSISTANT_STOP,
)
from homeassistant.core import HomeAssistant
import homeassistant.helpers.config_validation as cv
from homeassistant.helpers.event import async_track_time_interval
from homeassistant.helpers.typing import ConfigType

Expand All @@ -19,15 +26,31 @@
DEFAULT_SCAN_INTERVAL,
DOMAIN,
FORCE_RELOGIN_TIMEDELTA,
MULTIMATIC,
PLATFORMS,
RELOGIN_TASK_CLEAN,
SENSO,
SERVICES_HANDLER,
)
from .coordinator import MultimaticApi, MultimaticCoordinator
from .service import SERVICES, MultimaticServiceHandler

_LOGGER = logging.getLogger(__name__)

DATA_SCHEMA = vol.Schema(
{
vol.Required(CONF_USERNAME): cv.string,
vol.Required(CONF_PASSWORD): cv.string,
vol.Optional(CONF_SERIAL_NUMBER): cv.string,
vol.Required(CONF_APPLICATION, default=MULTIMATIC): vol.In([MULTIMATIC, SENSO]),
}
)

CONFIG_SCHEMA = vol.Schema(
{DOMAIN: DATA_SCHEMA},
extra=vol.ALLOW_EXTRA,
)


async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
"""Set up the multimatic integration."""
Expand Down
Loading

0 comments on commit f62970e

Please sign in to comment.