lmelon / homebridge-vaillant-vrc9xx

DEPRECATED - Homebridge plugin to control Vaillant Heating system
MIT License
20 stars 5 forks source link
deprecated

Deprecation warning: This project and repo is now deprecated and will not be maintained anymore. Vaillant has put in place some "protection" on their API to prevent this plugin to work correctly. Feel free to fork and update it for your personal need if you judge it useful for you.

DEPRECATED - homebridge-vaillant-vrc9xx

A plugin for homebridge, which allows to control Vaillant heater equipped with the VRC900 or VRC920 internet module.

It is a partial replacement for the multiMatic app available for iOS and Android.

Goal

Beside the pleasure of integrating everything into one single app (Home or Eve), the vaillant app has been a source of frustration for me since the beginning especially:

The first point is definitelly fixed by this plugin as homebridge will poll vaillant API every minute and record the last known state. I think this continuous polling helps keeping the connection with the internet gateway alive and even if it is broken for some reason, you would still have the last know state available which is better than nothing.

The second point is not fully adressed for now. I plan to build a better retry mechanism that would ensure your command eventually get executed even hours later one the connection with the gateway is restored. This is quite tricky because there is other sources of changes (the vaillant app, manually on the thermostat).

Remark I have to say I have seen improvement in the stability in the last two years. But there is still issues from time to time. I even put the VR900 on a connected plug so that I can reset the gateway remotely when it starts demonstrating weird behaviour.

Beside these points, integration with homekit bring additional benefits like richer automation (based on your location for example).

You can also adapt the temperature along the day (a bit cooler during the period of the day you are active and move a lot, a bit hotter when you are sitting in your coach watching TV).

I am also thinking to integrate predefined schedules that you could activate automatically (when you are away for the week-end for example).

Do not hesitate to let me know if additional features would be useful for you.

Status

HitCount Dependency Status devDependency Status Node version NPM Version

Supported Vaillant devices

In theory any Vaillant heater that can be controlled with the multiMatic app (iOS and Android) should work too.

Requirements

This might be an issue to upgrade an existing installation of homebridge. So remember that you can deploy a second (or third, ...) instance of homebridge next to an existing one: just change the username and port number in the config file.

Installation

After Homebridge has been installed, you can install it globally with the command:

sudo npm install -g homebridge-vaillant-vrc9xx

But instead of doing this, I would highly recommand using homebridge-config-ui-x to deploy and update your plugins.

Configuration

Below if the configuration with default values

{
  "bridge": {
      ...
  },
  "platforms": [
    {
      "platform": "VaillantVRC9xx",
      "api": {
                "debug": false,
                "polling": 300,
                "user": {
                    "name": "username",
                    "password": "password",
                    "device": "1234-56789-1011"
                },
                "rooms": {
                    "disabled": false,
                    "veto_duration": 180
                }
            }
    }
  ]
}
Attributes Usage
debug If set to "true", it will create a dump file with all queries to the Vaillant API allowing to debug any issue. DO NOT activate this permanently as it will create a huge dump file over time. The path to this dump file will be printed in the logs. The filename is "vaillant-query.log". Your password will not be output in the dump.
name The username used to connect the multiMatic app. I recommand creating a dedicated user for homebridge so that the plugin will never mess-up with your access. This is easily done from within the multiMatic app.
password The password of this user
device A unique identifier used to identify the "device". Just select any random sequence of number.
polling The polling interval (in seconds) the plugin uses to retrieve the state of the system. The communication between the cloud api and the VRC9xx module seems to occur every 5 minutes or so. So the default value is 300. The minimal value is 30 to avoid performing a Denial-of-Service (DoS) attack on the API servers
disabled Disable the room-by-room functionnality in case the API incorrectly report it as available
veto_duration When room-by-room (ambiSENSE / VR-50 & VR-51) is used, this parameter defines, in minutes, the duration of "Quick Veto", i.e. changes to the scheduled temperature when the room is in AUTO mode. When done from the Vaillant app, the default is 3 hours / 180 mins, so this is also the default here. This parameter is global for all rooms.

How it works

This configuration will connect to Vaillant API servers and get the full state of the system and create:

Remark

  • Inactive zones are ignored and will not show up in homekit
  • Zones for which individual rooms (see below) have been defined will not show up in homekit

Heating zone

Zones

The heating thermostat is fully functional. It will show the current temperature in the room the thermostat is located as well as the target temperature.

The target shown depends on the heating state. The heater can be in 4 states: OFF (completelly stopped), Reduced (Night mode), Day, Auto (alternate between night and day according to the schedule).

Behaviour:

Room by room (a.k.a ambiSENSE)

Multiple VR50 and one VR51 can be linked to 1 room. One thermostat will be defined for each room regardless of the number of devices in that room.

Note that when a room-by-room is active the corresponding zone becomes useless and not visible in the Vaillant app. So it will no show-up in homekit neither.

The heating thermostat representing the room is fully functional. It will show the current temperature in the room the thermostat is located as well as the target temperature.

Behaviour:

Domestic Hot Water

The domestic hot water is represented as a heating thermostat. Only a single target temperature is available.

Temperature Sensors

They come with historical data visible in the Eve app. Some are duplicated from the current temperature in the thermosat for easier access.

Contact Sensors

These sensors allow to monitor the connection between:

Please note that if the connection between the cloud and the gateway is broken for some reason, after some time the connection between homebridge and the cloud will fail too.

This is because Vaillant api generate an error when the installation is disconnected and you cannot get the last known info.

If this situation occurs during startup of homebridge, the plugin will never finish its initial setup (until the connection can finally be established). That also mean the homebridge instance will not be available.

Known limitations

Roadmap for enhancements

These are the few evolution that I have in mind. Do not hesitate to "vote" for them and/or to propose new items

Feel free to vote for your preferred features or propose new ones.

Contributing

You can contribute to this homebridge plugin in following ways:

Pull requests are accepted.

Comments and feedbacks

If you use this and like it - please leave a note by staring this package here or on GitHub.

If you use it and have a problem, file an issue at GitHub - I'll try and help.

If you tried this, but don't like it: tell me about it in an issue too. I'll try my best to address these in my spare time.

If you fork this, go ahead - I'll accept pull requests for enhancements.

License

MIT License

Copyright (c) 2019 L. Mélon

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.