hass-core/homeassistant/components/zwave_js

Z-Wave Integration

This document covers details that new contributors may find helpful when getting started.

Improving device support

This section can help new contributors learn how to improve Z-Wave device support within Home Assistant.

The Z-Wave integration uses a discovery mechanism to create the necessary entities for each of your Z-Wave nodes. To perform this discovery, the integration iterates through each node's Values and compares them to a list of discovery rules. If there is a match between a particular discovery rule and the given Value, the integration creates an entity for that value using information sent from the discovery logic to indicate entity platform and instance type.

In cases where an entity's functionality requires interaction with multiple Values, the discovery rule for that particular entity type is based on the primary Value, or the Value that must be there to indicate that this entity needs to be created, and then the rest of the Values required are discovered by the class instance for that entity. A good example of this is the discovery logic for the climate entity. Currently, the discovery logic is tied to the discovery of a Value with a property of mode and a command class of Thermostat Mode, but the actual entity uses many more Values than that to be fully functional as evident in the code.

There are several ways that device support can be improved within Home Assistant, but regardless of the reason, it is important to add device specific tests in these use cases. To do so, add the device's data to the fixtures folder and then define the new fixtures in conftest.py. Use existing tests as the model but the tests can go in the test_discovery.py module. To learn how to generate fixtures, see the following section.

Generating device fixtures

To generate a device fixture, download a diagnostics dump of the device from your Home Assistant instance. The dumped data will need to be modified to match the expected format. You can always do this transformation by hand, but the integration provides a helper script that will generate the appropriate fixture data from a device diagnostics dump for you. To use it, run the script with the path to the diagnostics dump you downloaded:

python homeassistant/components/zwave_js/scripts/convert_device_diagnostics_to_fixture.py <path/to/diagnostics/dump>

The script will print the fixture data to standard output, and you can use Unix piping to create a file from the fixture data:

python homeassistant/components/zwave_js/scripts/convert_device_diagnostics_to_fixture.py <path/to/diagnostics/dump> > <path_to_fixture_output>

You can alternatively pass the --file flag to the script and it will create the file for you in the fixtures folder: python homeassistant/components/zwave_js/scripts/convert_device_diagnostics_to_fixture.py <path/to/diagnostics/dump> --file

Switching HA support for a device from one entity type to another.

Sometimes manufacturers don't follow the spec properly and implement functionality using the wrong command class, resulting in HA discovering the feature as the wrong entity type. There is a section in the discovery rules for device specific discovery. This can be used to override the type of entity that HA discovers for that particular device's primary Value.

Adding feature support to complex entity types

Sometimes the generic Z-Wave entity logic does not provide all of the features a device is capable of. A great example of this is a climate entity where the current temperature is determined by one of multiple sensors that is configurable by a configuration parameter. In these cases, there is a section in the discovery rules for device specific discovery. By leveraging discovery_data_template.py, it is possible to create the same entity type but with different logic. Generally, we don't like to create entity classes that are device specific, so this mechanism allows us to generalize the implementation.

Architecture

This section describes the architecture of Z-Wave JS in Home Assistant and how the integration is connected all the way to the Z-Wave USB stick controller.

Connection diagram

Z-Wave USB stick

Communicates with devices via the Z-Wave radio and stores device pairing.

Z-Wave JS

Represents the USB stick serial protocol as devices.

Z-Wave JS Server

Forward the state of Z-Wave JS over a WebSocket connection.

Z-Wave JS Server Python

Consumes the WebSocket connection and makes the Z-Wave JS state available in Python.

Z-Wave integration

Represents Z-Wave devices in Home Assistant and allows control.

Home Assistant

Best home automation platform in the world.

Running Z-Wave JS Server

Z-Wave JS Server can be run as a standalone Node app.

It can also run as part of Z-Wave JS UI, which is also a standalone Node app.

Both apps are available as Home Assistant add-ons. There are also Docker containers etc.