search

joleys / niko-home-control-II

Home Assistant Custom Integration for Niko Home Control II
MIT License
74 stars 20 forks source link
automation domotics home-assistant home-automation niko

readme

Niko Home Control II Home Assistant Integration

License: MIT

This custom component will allow you to integrate you Niko Connected Controller II in Home Assistant. You can use a touchscreen profile or the Hobby API account.

This integration communicates directly with the controller. You only need internet when activating/renewing the Hobby API. If you use a touch screen profile, this isn't even needed.

IMPORTANT: There is an issue with the touch profiles, so the only supported way to configure the controller is the Niko Hobby API.

Acknowledgements

This custom component is a spin-off of the hard and excellent work by @filipvh. Thanks!

A big thanks to Johan and Koen from Niko for their support and providing the test equipment.

Some people who made this possible, and should be mentioned:

What works now?

Everything is developed against the Niko documentation. The version that was used can be found at docs/documentation.pdf.

General

The integration provides multiple devices and entities. See below for a list of entities that each type of device exposes.

Entities

The integration itself exposes the following entities:

NHC Access Control Action

This action is exposed as a switch (if supported), and a lock (if supported)

Entities

NHC All Off Action

This action is exposed as a button.

Entities

It has some extra entities that can be used in automations:

NHC Audio Control Action

This action is exposed as media player.

Entities

It has some extra entities that can be used in automations:

Not yet implemented

NHC Basic Alarm Action & NHC Panic Mode Action

Remark: this is untested as I don't own a device of this type.

This action is exposed as alarm control panel.

Entities

It has some extra entities that can be used in automations:

NHC BellButton Action

This action exposes a switch and a lock.

Entities

It has some extra entities that can be used in automations:

NHC Dimmer Action

This action is exposed as a light.

Entities

Services

The integration exposes a service to set the brightness of a light. This can be used to set the brightness without turning the lights on. For instance if you want your lights to have a certain brightness at night. See Developer Tools → Services → Niko Home Control II: Set brightness for light.

NHC Fan Action

This is exposed as a fan entity.

NHC Free Start Stop Actions

This action is exposed as a switch.

Entities

It has some extra entities that can be used in automations:

NHC Garage Door Action

This action is exposed as a cover.

Entities

NHC House Mode Actions

This action is exposed as a switch.

Entities

It has some extra entities that can be used in automations:

NHC HVAC Thermostat

This is exposed as a climate entity.

Entities

NHC Thermostat

This is exposed as a climate entity.

Entities

NHC Touch Switch

This is exposed as a climate entity.

Entities

NHC Mood Action

This action is exposed as a button.

Entities

It has some extra entities that can be used in automations:

NHC Motor Action

This is exposed as a cover entity.

Entities

NHC PIR Action

This action is exposed as a switch.

Remark: the switch represents the state of the override button. If you need the output of the PIR sensor in Home Assistant you can link a "Virtual on/off device" in the Niko Home Control Programming Software to be switched on when the PIR sensor initiates the routine.

NHC Presence Simulation Action

This action is exposed as a switch.

Entities

It has some extra entities that can be used in automations:

NHC Virtual flag

This is exposed as switch.

NHC Relay Action (light, socket, switched-fan, switched-generic)

Lights are exposed as lights. Others are exposed as switches.

NHC Reynaers Action

This is exposed as a cover entity.

Remark: this is untested as I don't own a device of this type.

Entities

NHC Velux Action

This is exposed as a cover entity.

Entities

NHC Zigbee Smart plug

This is the energy metering linked to a zigbee smart plug.

Remark: The smart plug itself can be controlled through the Status Switch. But it will also be exposed as a NHC Relay Action Switch.

Entities

Remark: The totals are not available as they are not (yet) exposed by the API.

Generic Zigbee Smart plug

This is the energy metering linked to a generic zigbee smart plug. The smart plug itself is a different device.

Entities

Remark: The totals are not available as they are not (yet) exposed by the API.

Calculated totals

Totals can be calculated via a Helper:

Goto 'Settings' > 'Devices & Services' and click 'Helpers' at the top. Click the '+ Create Helper' button at the bottom right and select 'Integration - Riemann sum integral sensor'. Type a name for the Helper and select the relevant ' energyhome' entity (i.e. 'Electrical Power to Grid') from the 'Input sensor' dropdown. Integration method 'Trapezoidal rule' should give the most accurate integrated value. Set 'Precision' to '3' and set the 'Metric prefix' to 'k (kilo)'. Leave the time unit at 'Hours'.

At least two helpers are needed: one for the consumption total and one for the production total. These helpers can be used in the HA Energy Dashboard.

Electricity Metering module (with clamp) & NHC ZigBee Electricity Metering module (with clamp)

Entities

Remark: The totals are not available as they are not (yet) exposed by the API.

Energy Home

Entities

Remark: There a more properties to this device, but these are not documented so it is difficult to know what they report exactly.

Generic Ventilation Implementation

This is exposed as a fan entity.

Entities

Remark: Some ventilation systems can not be turned off. Home Assistant Fan Entity does not support this. This means you will be able to turn it off in Home Assistant, but this will not have any effect.

Generic Heating/Cooling Implementation

This is exposed as a climate entity.

Entities

Generic Warm Water Implementation

Entities

Generic ZigBee Heating/Cooling Implementation

Remark: this is untested as I don't own a device of this type.

This is exposed as a climate entity.

Entities

NHC Player status action

Remark: this is untested as I don't own a device of this type.

Remark: This device can not be controlled. It is a virtual device that shows the status for another player.

Entities

NHC Thermo switch

Remark: this is untested as I don't own a device of this type.

Entities

NHC Virtual Thermostat

This is exposed as a climate entity.

Remark: this is untested as I don't own a device of this type.

Entities

RobinsIP Videodoorstation

Remark: This device is not documented/supported by Niko.

This is exposed as a camera.

Remark: Note that this will only work if your camera is not directly connected to the controller. The controller uses its own DHCP server and there is nothing in place to connect to the streams. In older versions of the controller there was port forwarding, but this is disabled (confirmed by Niko).

Entities

Mute/Unmute/Hangup

Add the following Shell Commands in your configuration.yaml.

shell_command:
  doorphone_hangup: curl -u admin:123qwe http://192.168.X.X/api/v1/call_hangup
  doorphone_mute: curl -u admin:123qwe http://192.168.X.X/api/v1/mute_set?mute=tones_incoming
  doorphone_unmute: curl -u admin:123qwe http://192.168.X.X/api/v1/mute_set?mute=off

Remark: Replace the IP address with the IP address of your doorstation. Note that this will only work if your camera is not directly connected to the controller.

More information can be found in the API documention and manual of the RobinsIP doorstation:

NHC Condition Action

Remark: This device is not documented/supported by Niko.

This is exposed as a switch.

NHC Timeschedule Action

Remark: This device is not documented/supported by Niko.

Entities

NHC Heating Cooling Action

Remark: This device is not documented/supported by Niko.

Entities

Electrical Heating Action

Remark: This device is not documented/supported by Niko.

This action is exposed as a button.

Entities

Generic Inverter

Remark: This device is not documented/supported by Niko.

Entities

Peakmode Action

This action is exposed as a button.

Entities

It has some extra entities that can be used in automations:

Easee Chargingstation

Remark: This device is not documented/supported by Niko.

This is exposed as a switch.

Entities

Not yet supported

How to get it running

Note: Make sure you have a recent version of Home Assistant!

This integration is not part of the default Home Assistant installation.

The easiest way to install it is through HACS (Home Assistant Community Store). Once you have HACS installed you can search for "Niko Home Control II". Make sure you select the correct one. Ours has the following description:

Home Assistant Custom integration for Niko Home Control II

Once this is done you can install the integration in Home Assistant:

  1. Go to Settings → Devices & Services Integrations
  2. Add an integration, search for Niko Home Control II, and click on it
  3. Follow the wizard

FAQ

The integration is not working after power outage

It is expected behouviour that the integration may not work after a power outage. Please restart Home Assistant. or after a new configuration is uploaded.

The integration is not working after uploading a new configuration

if you uploaded a new configuration to the connected controller / hub, please restart Home Assistant.

The integration is not working after an IP change

Please make sure that the IP of the connected controller / hub does not change. If the IP changes you will need to remove and re-add the integration.

I see a lot of "Report Instant Usage re-enabled" messages in the log

This will only appear in the logs if you have set your log-level to debug.

The Electricity Metering module (with clamp), Energy Home, NHC Zigbee Smart plug and Generic Zigbee Smart plug only report their power usage for 30 seconds when the "Report Instant Usage" is enabled. So as soon as it becomes disabled this integration re-enables it.

I see "Class CocoXXX not found" in the log

This is because this device is not supported (yet) or this device can't be controlled through the API.

Feel free to create an issue on Github. Please include your device list.

I don't have/use the Energy Home, but it is present in the integration

Each installation exposes an Energy Home device. At this point there is no good way to detect if the Energy Home is used.

If you do not want to see / record / ... you can disable the device in the integration.

I need to see the device list

First you will need to enable debug logging for the integration. You can enable debug logging for this integration by adding the following to your configuration.yaml file:

logger:
  default: warning
  logs:
    custom_components.nhc2: debug

When this is done you will need to restart Home Assistant. After that you can see the device list in the logs. You can find it by searching for Received device list:. The device list itself is a large JSON string.

If you don't feel comfortable sharing this device list in a public issue, you can send it to me via mail: niko-ha [at] verkoyen [dot] eu.

Development

Adding support for new Device models

Testing without having the real devices?

If you don't own a device but want to test the integration, and you have the relevant device info (eg. through a device list your received). You can fake the devices returned from the MQTT broker.

  1. Create a folder debugging in the root of the project.
  2. Add the device list json in this folder.
  3. Open coco.py
  4. Search for def _process_devices_list(self, response): and edit the code to look like:
def _process_devices_list(self, response):
    """Convert the response of devices.list into device instances."""
    _LOGGER.debug(f'Received device list: {response}')

    # REMOVE ME START
    from pathlib import Path
    import ast

    path = Path(str(Path(__file__).parent.resolve()) + '/../../../debugging/device_list.json').resolve()
    f = open(path)
    response = ast.literal_eval(f.read())
    # REMOVE ME END

Remark: This is a hackish way, and you will not able to test it for real. You will not receive updates. Check the logs to see if messages are correctly send to the MQTT broker.

Found a bug?

If you found a bug you can create an issue on GitHub.

Before creating an issue:

  1. Check if the issue is already reported
  2. Make sure you are running the latest version of Home Assistant.
  3. Make sure you are running the latest version of this integration.

If you create an issue:

logger:
  default: warning
  logs:
    custom_components.nhc2: debug

Want to help?

As you can see in this README, there are still untested devices. These are devices that are implemented based on the available documentation from Niko. If you own one of these devices, please help me out by testing it. Let us know, through an issue, what is working or not.

If you see missing features, feel free to create pull requests. Add missing devices, ...