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

Commit

Permalink
1.5.0 release (#44)
Browse files Browse the repository at this point in the history
1.5.0 release
  • Loading branch information
thomasgermain authored Apr 13, 2021
1 parent 1456a86 commit 6f9f0ce
Show file tree
Hide file tree
Showing 41 changed files with 1,445 additions and 1,032 deletions.
119 changes: 79 additions & 40 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# vaillant-component
# multimatic-component

**Please note that this component is still in beta test, so I may do (unwanted) breaking changes.**

Ideas are welcome ! Don't hesitate to create issue to suggest something, it will be really appreciated.

Please download the `vaillant` folder and put it inside your `custom_components` folder.
Please download the `multimatic` folder and put it inside your `custom_components` folder.

You can configure it through the UI using integration.
You have to provided your username and password (same as multimatic app)

**It is strongly recommended to use a dedicated user for HA**, for 2 reasons:
- As usual for security reason, if your HA is compromised somehow, you know which user to block
- I cannot strongly confirm it, but it seems vaillant API only accept the same user to be connected at the same time
- As usual for security reason, if your HA got compromise somehow, you know which user to block
- I cannot confirm it, but it seems multimatic API only accept the same user to be connected at the same time


## Releases
Expand Down Expand Up @@ -41,13 +41,13 @@ First release using config flow
If you have any issue with refresh time of the data, you can use an automation to call the service. **I recommend to do it very 1 hour**. If you really hove data refresh issue, you can do down until every 30min. Doing it more often will likely end up in an error at vaillant API.
You can use something like this as automation:
```yaml
- id: "Refresh vaillant data"
alias: "Refresh vaillant data"
- id: "Refresh multimatic data"
alias: "Refresh multimatic data"
trigger:
- platform: time_pattern
hours: "/1"
action:
- service: vaillant.request_hvac_update
- service: multimatic.request_hvac_update
```
### [1.3.1](https://github.com/thomasgermain/vaillant-component/releases/tag/1.3.1)
- check if a zone is enabled before creating a climate entity.
Expand All @@ -59,52 +59,92 @@ You can use something like this as automation:
- **BREAKING CHANGES** on vaillant mode <> hvac mode & preset mode, please see `Expected behavior` below


### [1.5.0](https://github.com/thomasgermain/vaillant-component/releases/tag/1.5.0)
**BREAKING CHANGES** Foreseen some time for the migration:
- Renaming integration from `vaillant` to `multimatic`
- entity_id doesn't contain anymore the domain (e.g: `climate.vaillant_bathroom` becomes `climate.bathroom`).
Only few entities keep the domain inside their id (`quick_mode`, `holiday`, `system_online`, `system_update` and `errors`),
otherwise, the name is too generic
- Services are also renamed from `vailant.xxx` to `multimatic.xxx`
- Add `multimatic` in unique_id in order to avoid collision
- Dynamic errors are removed in favor of a single binary_sensor (`binary_sensor.multimatic_errors`). This is
much easier to create an automation

**Other changes:**
- Moving to `DataUpdateCoordinator`
- Allowing multiple instance of the integration
- IO optimization when quick mode or holiday mode is changing.
- Add scan interval option
- Fix error when a live report is not available from the API anymore
- Add fan support
- Fix for room climate to detect if the room is heating or not
- Add `version` in the manifest (for HA 2021.4.x)

**You may sometimes see (around 3:30 am) an error like the following.
It seems the API server is restarted every night, so the integration can't fetch data.
I can't do anything about that.**
```
Unable to fetch data from multimatic, API says:`xxx Service Unavailable, status: xxx
```
**How to migrate ?**
1) Delete `vaillant` integration from HA UI
2) Delete `vaillant` folder from `custom_component`
3) Copy `multimatic` folder (from [1.5.0 release](https://github.com/thomasgermain/vaillant-component/releases/tag/1.5.0))
and past it to `custom_component`
4) Restart HA
5) Add `multimatic` integration from HA UI
6) The hard job is starting now, you have to find old entity_id you were using in automation or somewhere else.
You can do some find and replace (e.g. `climate.vaillant_bathroom`-> `climate.bathroom`)
## Provided entities
- 1 water_heater entity, if any water heater: `water_heater.vaillant_<water heater id>`, basically `water_heater.vaillant_control_dhw`
- 1 climate entity per zone (expect if the zone is controlled by room) `climate.vaillant_<zone id>`
- 1 climate entity per room `climate.vaillant_<room name>`
- 1 binary_sensor entity `binary_sensor.vaillant_control_dhw` reflecting if the circulation is on or off
- 1 binary_sensor entity `climate.vaillant_<room name>_window` per room reflecting the state of the "open window" in a room (this is a feature of the vaillant 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.vaillant_<sgtin>_lock`per device reflecting if valves are "child locked" or not
- 1 binary_sensor entity `binary_sensor.vaillant_<sgtin>_battery` reflecting battery level for each device (VR50, VR51) in the system
- 1 binary_sensor entity `binary_sensor.vaillant_<sgtin>_battery` reflecting connectivity for each device (VR50, VR51) in the system
- 1 binary_sensor entity `binary_sensor.vaillant_system_update`to know if there is an update pending
- 1 binary_sensor entity `binary_sensor.vaillant_system_online` to know if the vr900/920 is connected to the internet
- 1 binary_sensor entity `binary_sensor.vaillant_<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.vaillant_outdoor_temperature` for outdoor temperature
- 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 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.<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.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 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.vaillant_quick_mode` to know a quick mode is running on
- 1 binary sensor ` binary_sensor.vaillant_holiday` to know the holiday mode is on/off
- dynamic binary sensors if there are extra errors coming from the api.
- 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`)
## Provided devices
- 1 device per VR50 or VR51
- 1 device for the boiler (if supported). Some boiler 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 vaillant API)
- 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 found
- the 'real vaillant mode' running on (AUTO, MANUAL, DAY, etc)
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 found
- the last update (this is not the last HA update, this is the last time vaillant checks the boiler)
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)
- the title (human-readable description of the status code)
For the `binary_sensor.vaillant_quick_mode`, when on, you have the current quick mode name is available
For the `binary_sensor.vaillant_holiday`, when on, you have the start date, end date and temperature
For the `binary_sensor.multimtic_quick_mode`, when on, you have the current quick mode name is available
For the `binary_sensor.multimtic_holiday`, when on, you have the start date, end date and target temperature
## Provided services
- `vaillant.set_holiday_mode` to set the holiday mode (see services in HA ui to get the params)
- `vaillant.remove_holiday_mode` .. I guess you get it
- `vaillant.set_quick_mode` to set a quick mode
- `vaillant.remove_quick_mode` don't tell me you don't get it
- `vaillant.set_quick_veto` to set a quick veto for a climate entity
- `vaillant.remove_quick_veto` to remove a quick veto for a climate entity
- `vaillant.request_hvac_update` to tell vaillant API to fetch data from your installation and made them available in the API
- `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.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
This will allow you to create some buttons in UI to activate/deactivate quick mode or holiday mode with a single click
Expand Down Expand Up @@ -141,5 +181,4 @@ Modes mapping:
- `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`

- `QM_COOLING_FOR_X_DAYS` -> no hvac & `PRESET_COOLING_FOR_X_DAYS`
90 changes: 90 additions & 0 deletions multimatic/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
"""The multimatic integration."""
import asyncio
import logging

from homeassistant.config_entries import ConfigEntry
from homeassistant.const import EVENT_HOMEASSISTANT_STOP
from homeassistant.core import HomeAssistant

from .const import DOMAIN, HUB, PLATFORMS, SERVICES_HANDLER
from .hub import ApiHub
from .service import SERVICES, MultimaticServiceHandler

_LOGGER = logging.getLogger(__name__)


async def async_setup(hass: HomeAssistant, config: dict):
"""Set up the multimatic integration."""
return True


async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry):
"""Set up multimatic from a config entry."""

api: ApiHub = ApiHub(hass, entry)
await api.authenticate()
await api.async_refresh()

hass.data.setdefault(DOMAIN, {})
hass.data[DOMAIN].setdefault(entry.unique_id, {})
hass.data[DOMAIN][entry.unique_id][HUB] = api

for platform in PLATFORMS:
hass.async_create_task(
hass.config_entries.async_forward_entry_setup(entry, platform)
)

async def logout(param):
await api.logout()

hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STOP, logout)

await async_setup_service(api, hass)

return True


async def async_setup_service(api: ApiHub, hass):
"""Set up services."""
if not hass.data.get(SERVICES_HANDLER):
service_handler = MultimaticServiceHandler(api, hass)
for service_key in SERVICES:
schema = SERVICES[service_key]["schema"]
if not SERVICES[service_key].get("entity", False):
hass.services.async_register(
DOMAIN, service_key, service_handler.service_call, schema=schema
)
hass.data[DOMAIN][SERVICES_HANDLER] = service_handler


async def async_unload_services(hass):
"""Remove service when integration is removed."""
service_handler = hass.data[DOMAIN].get(SERVICES_HANDLER, None)
if service_handler:
for service_name in SERVICES:
hass.services.async_remove(DOMAIN, service_name)


async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry):
"""Unload a config entry."""
unload_ok = all(
await asyncio.gather(
*[
hass.config_entries.async_forward_entry_unload(entry, component)
for component in PLATFORMS
]
)
)
if unload_ok:
hass.data[DOMAIN].pop(entry.unique_id)

_LOGGER.debug("Remaining data for multimatic %s", hass.data[DOMAIN])

if (
len(hass.data[DOMAIN]) == 1
and hass.data[DOMAIN].get(SERVICES_HANDLER, None) is not None
):
await async_unload_services(hass)
hass.data[DOMAIN].pop(SERVICES_HANDLER)

return unload_ok
Loading

0 comments on commit 6f9f0ce

Please sign in to comment.