May 08, 2021 Network and group info. The Z-Wave network info screen is available under Setup hardware. If there is a Z-Wave controller in the system (a USB-stick for instance), there is a 'Setup' button beside it. Click this and the list of controlled nodes appears. At the top right the node management button houses the 'groups & network' button. Our free mobile-friendly tool offers a variety of randomly generated keys and passwords you can use to secure any application, service or device. Simply click to copy a password or press the ' Generate ' button for an entirely new set. Remove all the Z-Wave nodes except the controller from the current setup. Delete the Z-Wave integration. Power down the computer. Remove the Z-Wave Controller stick. Power on the computer. Make sure Home Assistant comes back up, but without Z-Wave stuff. Add the path and network key to configuration.yaml. Power down the computer. Our free mobile-friendly tool offers a variety of randomly generated keys and passwords you can use to secure any application, service or device. Simply click to copy a password or press the ' Generate ' button for an entirely new set.

This integration allows you to control a Z-Wave network via the Z-Wave JS driver. This is our recommended Z-Wave integration for Home Assistant.

Please review the limitations below before you get started as a few devices still may not work or only work partially.

Quick start (Home Assistant including Supervisor)

To add Z-Wave JS to your installation, plug the Z-Wave stick into the device that runs Home Assistant. Then Go to Configuration >> Integrations in the UI. Click the “Add integration” button in the bottom right and from the list of integrations, select “Z-Wave JS” and follow the instructions shown.

Note: A new network key is automatically generated for you. If this Z-Wave stick has already paired with secure devices, you need to enter the previously used network key. Make sure that you keep a backup of this key in a safe place in case you need to move your Z-Wave stick to another device.

If you do not run Home Assistant OS (the default installation type) or Home Assistant Supervised, please see the advanced installation instructions.

Using Z-Wave

When the Z-Wave integration starts up, it will interview your entire Z-Wave network. Depending on the number of devices paired with the Z-Wave stick, this can take a while. Information about your devices is stored in cache files by Z-Wave JS. Be aware that (re)starting the Z-Wave server will cause your network to be (partially) unresponsive until the interview process is done.

While your Z-Wave mesh is permanently stored on your stick, the additional metadata is not. When you lose the cache files (for example by switching between any of the below-mentioned ways to run the server) all your nodes will have to be re-interviewed again before they can be properly controlled. You can speed up this process by manually waking up your battery-powered devices. Most of the time this is a press on the button on those devices (see their manual). It is not needed to exclude/re-include devices from the mesh. Just be patient and the devices will appear.

Advanced users: Make sure that the server started successfully by inspecting the logs. Give the Z-Wave controller some time to start.

Configuration

Adding Z-Wave JS to your Home Assistant instance can be done via the userinterface, by using this My button:

If the above My button doesn’t work, you can also perform the following stepsmanually:

• Browse to your Home Assistant instance.
• In the sidebar click on Configuration.
• From the configuration menu select: Integrations.
• In the bottom right, click on theAdd Integration button.
• From the list, search and select “Z-Wave JS”.
• Follow the instruction on screen to complete the set up.

Services

Service zwave_js.set_config_parameter

Generate Zwave Network Key Random Number

This service will update a configuration parameter. To update multiple partial parameters in a single call, use the zwave_js.bulk_set_partial_config_parameters service.

Examples of setting a single parameter value

Let’s use parameter 31 for this device as an example to show examples of different ways that the LED 1 Blink Status (bottom) partial parameter can be set. Note that in places where we are using different values for the same key, the different values are interchangeable across the examples. We can, for instance, use 1 or Blink interchangeably for the value in all of the examples.

Example 1:

Example 2:

Example 3:

Service zwave_js.bulk_set_partial_config_parameters

This service will bulk set multiple partial configuration parameters. Be warned that correctly using this service requires advanced knowledge of Z-Wave to use correctly.

Examples of bulk setting partial parameter values

Let’s use parameter 21 for this device as an example to show how partial parameters can be bulk set. In this case, we want to set 0xff to 127, 0x7f00 to 10, and 0x8000 to 1 (or the raw value of 4735).

When using the dictionary format to map the partial parameter to values, the cached values for the missing partial parameters will be used. So in examples 2, 3, 4, and 5, the service would use the cached value for partial parameters 0xff0000, 0x3f000000, and 0x40000000 because new values haven’t been specified. If you send the raw integer value, it is assumed that you have calculated the full value, so in example 1, partial parameters 0xff0000, 0x3f000000, and 0x40000000 would all be set to 0.

Example 1:

Example 2:

Example 3:

Example 4:

Example 5:

Service zwave_js.refresh_value

This service will refresh the value(s) for an entity. This service will generate extra traffic on your Z-Wave network and should be used sparingly. Updates from devices on battery may take some time to be received.

Service zwave_js.set_value

This service will set a value on a Z-Wave device. It is for advanced use cases where you need to modify the state of a node and can’t do it using native Home Assistant entity functionality. Be warned that correctly using this service requires advanced knowledge of Z-Wave. The service provides minimal validation and blindly calls the Z-Wave JS API, so if you are having trouble using it, it is likely because you are providing an incorrect value somewhere. To set a config parameter, you should use the zwave_js.set_config_parameter or zwave_js.bulk_set_partial_config_parameters services instead of this one.

Service zwave_js.set_lock_usercode

This service will set the usercode of a lock to X at code slot Y.Valid usercodes are at least 4 digits.

Service zwave_js.clear_lock_usercode

This service will clear the usercode of a lock in code slot X.Valid code slots are between 1-254.

Events

There are two types of events that are fired, notification events and value notification events. You can test what events come in using the event developer tools in Home Assistant and subscribing to the zwave_js_notification or zwave_js_value_notification events respectively. Once you know what the event data looks like, you can use this to create automations.

Node events (Notification)

Check the Z-Wave JS notification event documentation for an explanation of the notification event data. These events fire with the zwave_js_notification event type.

Notification Command Class

These are notification events fired by devices using the Notification command class. The parameters attribute in the example below is optional, and when it is included, the keys in the attribute will vary depending on the event.

Entry Control Command Class

These are notification events fired by devices using the Entry Control command class.

Scene events (Value Notification)

Value Notifications are used for stateless values, like Central Scenes and Scene Activation. These events fire with the zwave_js_value_notification event type.

Value Notification example:

Value updated events

Due to some devices not following the Z-Wave spec, there are scenarios where a device will send a value update but a state change won’t be detected in Home Assistant. To address the gap, the zwave_js_value_updated event can be listened to to capture any value updates that are received by an affected entity. This event is enabled on a per device and per entity domain basis, and the entities will have assumed_state set to true. This change will affect how the UI for these entities look; if you’d like the UI to match other entities of the same type where assumed_state is not set to true, you can override the setting via entity customization.

The following devices currently support this event:

Value Updated example:

This event can be used to trigger a refresh of values when the new state needs to be retrieved. Here’s an example automation:

Current Limitations

As this integration is still in the early stages there are some important limitations to be aware of.

• While support for the most common devices is working, some command classes are not yet (fully) implemented in Z-Wave JS. You can track the status here.
• There currently is no migration path available from any of the other Z-Wave implementations in Home Assistant. Your Z-Wave network is however stored on your stick so migrating will only require you to redo your device and entity naming.

You can keep track of the Roadmap for the Z-Wave JS integration here.

Migrating from previous Z-Wave implementations

If you are currently running on the zwave or ozw Z-Wave integration and it works fine, there is no need to switch over at this time to Z-Wave JS. It is important to know is that most development focus currently goes to Z-Wave JS. The previous implementations are still provided as-is. They will NOT be removed without proper notice but in time there might come technical dependencies that render one or both of those integrations unusable.

If you’re new to Home Assistant, use Z-Wave JS.

The zwave integration has been marked as deprecated and will no longer receive any updates like new device files. The ozw integration will receive new device files if they are provided by upstream.

It is perfectly doable to switch over from one of the above mentioned previous integrations to the new Z-Wave JS integration. The good news is that your entire Z-Wave network is stored on your stick so you will not have to run through your house to recreate your network. That said, we currently do not provide a full-fledged, worry-free, click-a-button, migration from old to new. We’re exploring options to provide this in the future. This means that if you want to switch over now, you will be the migration wizard.

In a nutshell this is what the migration path looks like

1. Make a backup of your Home Assistant configuration. If you’re running the supervisor this is very easy to do by creating a snapshot. You should do this so you’ll be able to quickly revert if you may run into unexpected problems.

   Write down/copy your Z-Wave network key somewhere, you are going to need it later.
   Make a list of what node ID belongs to each device. Your network (Nodes and their config etc) is stored on the stick but the names you gave your devices and entities are not. This step is optional but will save you a lot of time later.

2. Remove the Z-Wave integration from Home Assistant: Configuration –> Integrations –> Z-Wave (or OpenZWave) –> Press the three dots and click Remove.

3. If you were running the OpenZWave beta, make sure to stop (or even remove) the OpenZWave add-on, also make sure it doesn’t start automatically at startup.

4. Restart your Home Assistant host. This step is important to make sure that your Z-Wave stick is released by the operating system.

5. Install the Z-Wave JS Server of your choice. If you run the supervisor and you’d like to run the standard add-on, you can skip this step if you want. The add-on is installed automatically for you when you choose so in the integration set-up. Remember to fill in the network key you’ve saved before.

6. Set up the Z-Wave JS integration and connect it to the server. You should see your nodes being detected by Home Assistant. Carefully watch if the status of the node is “ready”. This means it’s been fully interviewed (and those details cached) by the Z-Wave JS driver. Battery-powered nodes will only be interviewed when they wake up (at scheduled intervals) which can take from a few hours to a few days. To speed that up, you might want to consider waking the device up once. The manual of your device will tell you how to do a manual wake.

7. Once a node hits the ready state, the entities will be created (so not before). Only at this point, is it safe to rename the device (and so its entities). You will thank yourself at this point for having that list noted down of nodes and their names. This is actually the only real hard part of the migration as you will need to name all your devices again.

8. Enjoy your super fast up-to-date Z-Wave network in Home Assistant with support for all modern devices!

Need more help with your migration to Z-Wave JS?

There are a few topics created on the forums that might be of your interest:

You can also visit the #zwave channel on our discord.

Advanced installation instructions

The above instructions won’t work if you are using Home Assistant Container, Home Assistant Core, or you don’t want to use the built-in Z-Wave JS Server add-on. Below you’ll find the more detailed set-up instructions that covers all use cases.

Requirements

Controlling your Z-Wave network using the Z-Wave JS integration has the following requirements:

1. Run Z-Wave JS Server. This application provides the connection between your Z-Wave USB stick and Home Assistant. This server runs separately from Home Assistant so your Z-Wave mesh will keep running if you restart or stop Home Assistant. The Home Assistant Z-Wave JS integration connects to this server via a websocket connection. You need to run this Z-Wave server before you can use the integration.

2. Supported Z-Wave dongle. The Z-Wave controller dongle should be connected to the same host as where the Z-Wave JS server is running. In the configuration for the Z-Wave server you need to provide the path to this stick. It’s recommended to use the /dev/serial-by-id/yourdevice version of the path to your stick, to make sure the path doesn’t change over reboots. The most common known path is /dev/serial/by-id/usb-0658_0200-if00.

3. A network key. This key is used in order to connect securely to compatible devices. The network key consists of 32 hexadecimal characters, for example 2232666D100F795E5BB17F0A1BB7A146 (do not use this one, pick a random one). Without a network key security enabled devices cannot be added securely and will not function correctly. You must provide this network key in the configuration part of the Z-Wave JS Server. For new installations, a unique default key will be auto generated for you. TIP: You could use a site like random.org to create your own random network key. Make sure that you keep a backup of this key in a safe place. You will need to enter the same key to be able to access the securely paired devices.

4. The Z-Wave JS integration in Home Assistant. This integration connects to the Z-Wave JS Server to retrieve the info from your Z-Wave network and turns it into Home Assistant devices and entities.

Running the Z-Wave JS Server

As stated in the above requirements, you need to run the Z-Wave JS Server somewhere in your network. There are multiple ways to run this server, we’ll explain the most common ways below:

1. The official Z-Wave JS add-on, available from the add-on store

This option is only available for Home Assistant OS (the recommended installation type) and Home Assistant Supervised installations.

This add-on runs the Z-Wave JS server. It can be automatically installed and configured by Home Assistant as part of setting up the integration. You can also set it up manually.

The Z-Wave network can be configured via the built-in Z-Wave JS control panel in Home Assistant.

2. The Z-Wave JS to MQTT add-on installed available from the community add-on store

This option is only available for Home Assistant OS (the recommended installation type) and Home Assistant Supervised installations.

This add-on includes the Z-Wave JS Server as part of the Z-Wave JS 2 MQTT application. Despite the name, MQTT is not required to run this add-on.

The Z-Wave network can be configured via the built-in Z-Wave JS control panel in Home Assistant and via the Z-Wave JS control panel built into Z-Wave JS 2 MQTT.

Despite what the name suggests, you can actually run this add-on without MQTT enabled. In that case, it will provide you with a full-fledged, attractive and feature-complete UI to manage your Z-Wave nodes and settings.

3. The Z-Wave JS to MQTT Docker container

This is the recommended approach if you’re running Home Assistant Container. See the zwavejs2mqtt documentation for instructions.

After installing the Docker image, make sure you enable the Z-Wave JS Server in the configuration.

4. Run the Z-Wave server yourself

This is considered a very advanced use case. In this case you run the Z-Wave JS Server or zwavejs2mqtt NodeJS application directly. Installation and maintaining this is out of scope for this document. See the Z-Wave JS server or zwavejs2mqtt GitHub repository for information.

Installing and configuring the Z-Wave JS integration in Home Assistant

Once you have the Z-Wave server up and running, it’s time to configure the integration in Home Assistant. This integration can be configured using the integrations in the Home Assistant frontend:

1. Click on the + sign to add an integration and click on Z-Wave JS.

2. If you’re running full Home Assistant with supervisor, you will be presented with a dialog that asks if you want to use the Z-Wave JS Supervisor add-on. Check the box if you prefer this option. If you run the server yourself, or prefer the alternative zwavejs2mqtt addon, uncheck this box. After completing the configuration flow, the Z-Wave JS integration will beavailable.

3. If you’re not running the supervisor or you’ve unchecked the above mentioned box, you will be asked to enter a websocket URL (defaults to ws://localhost:3000). It is very important that you fill in the correct (docker) IP/hostname here. For example for the Z-Wave JS to MQTT add-on this is ws://a0d7b954-zwavejs2mqtt:3000.

Frequently Asked Questions

What Z-Wave devices are currently supported?

See the Z-Wave JS device database.

Can I switch between the Official Z-Wave JS add-on and Z-Wave JS to MQTT?

You can, but you cannot run them at the same time. Only one of them can be active at the same time.

When you switch add-ons, re-add the Z-Wave integration to Home Assistant with the new/updated WebSocket URL. There will be a popup raised that this Z-Wave network is already configured but “under the hood” the WebSocket URL is adjusted.

I do not see any entities created for my device in Home Assistant

Entities will be created only after the node hits the ready state (interview is completed). Also, note that some devices (like button remotes) do not create any entities but will only provide events when a button is pressed. See the events section on how to handle those events in your automations. If you are certain that your device should have entities and you do not see them (even after a restart of Home Assistant Core), that will be the time to create an issue about your problem on the GitHub issue tracker, see below section of troubleshooting issues.

Is there a way to easily export a dump of all my current Z-Wave nodes before I migrate?

You can run the script below in the Developer Tools to get a full oversight of your nodes and their entities.

How can I add (include) a new device to my Z-Wave network?

1. In Home Assistant: open Configuration -> Integrations -> Z-Wave JS -> Configure.
2. Press Add node.
3. Press Start Inclusion. The Z-Wave controller is now in inclusion mode and will not respond to other commands.
4. Put the device you want to add in inclusion mode. Refer to its manual how this is done.
5. The UI should confirm that the node was added and it will be immediately visible in Home Assistant. After a short while (seconds to minutes) the entities should also be created.
6. If the controller fails to add/find your device, cancel the inclusion process (to unblock your network again). In some cases it might help to first remove a node (exclusion) before you add it, even when the device has not been added to this Z-Wave network yet. Another approach would be to factory reset the device. Info about that is in the manual of your device.

How can I remove (exclude) a device from my Z-Wave network?

1. In Home Assistant: open Configuration -> Integrations -> Z-Wave JS -> Configure.
2. Press Remove node.
3. Press Start Exclusion. The Z-Wave controller is now in exclusion mode and will not respond to other commands.
4. Put the device you want to remove in exclusion mode. Refer to its manual how this is done.
5. The UI should confirm that the node was removed and the device and entities will be removed from Home Assistant.

Where do I need to enter the network key?

• You enter the network key during integration setup if you do not have the add-on installed.
• Official Z-Wave JS add-on: In the add-on configuration, directly in the supervisor.
• Z-Wave JS 2 MQTT: In the web UI, go to Settings -> Z-Wave -> Network Key.

How can I use my OZW network key in zwavejs2mqtt?

You can use your existing network key in zwavejs2mqtt but you need to slightly adjust it.The OZW looks like this: 0x01, 0x02, 0x03 etc. while the network key format accepted in zwavejs2mqtt looks like this 0102030405 etc.. You can simply edit your existing key and remove the '0x' part and the ', ' part so it becomes one large string of numbers.

What’s the benefit of using Z-Wave JS to MQTT over the official Add-On?

The official add-on provides the Z-Wave Server in it’s bare minimum variant, just enough to serve the Home Assistant integration.The Z-Wave JS to MQTT project includes the Z-Wave JS Server for convenience but also provides a Z-Wave Control panel and the ability (hence its name) to serve your Z-Wave network to MQTT. You can leave the MQTT Gateway disabled and only use the Control panel but you can even have the MQTT features enabled at the same time. For example to interact with Z-Wave from other devices, while the Home Assistant integration still works (as long as you keep the WS Server enabled in zwavejs2mqtt).

Z-Wave JS to MQTT seems to provide Home Assistant integration on its own too, now I’m confused

Correct, the Z-Wave (JS) to MQTT project existed before Home Assistant even had plans to move to the Z-Wave JS Driver.The Home Assistant integration that exists in zwavejs2mqtt is based on MQTT discovery.The official Z-Wave JS integration is not based on MQTT and is talking directly to the Z-Wave JS Driver (using the WS Server). This gives a better experience.

Can I run Z-Wave JS to MQTT only for the control panel and nothing else?

Sure, in the settings of zwavejs2mqtt, make sure to enable “WS Server” and disable “Gateway”.

My device does not automatically update its status in HA if I control it manually

Your device might not send send automatic status updates to the controller. While the best advice would be to update to recent Z-Wave Plus devices, there is a workaround with active polling (request the status) at some interval. See the section below for more info about this.

What about polling of devices?

Some legacy devices don’t report all their values automatically and require polling to get updated values when controlled manually. Z-Wave JS does not automatically poll devices on a regular basis without user interaction. Polling can quickly lead to network congestion and should be used very sparingly and only where necessary.

• In an upcoming release of Home Assistant we will provide a service to allow you to manually poll a value, for example from an automation that only polls a device when there is motion in that same room. If you really need polling, you can enable this in zwavejs2mqtt but not in the official add-on.

• zwavejs2mqtt allows you to configure scheduled polling on a per-value basis, which you can use to keep certain values updated. It also allows you to poll individual values on-demand from your automations, which should be preferred over blindly polling all the time if possible.

Wireless Network Key Netgear

My device is recognized as Unknown Manufacturer and/or some of its functionalities do not work in Z-Wave JS

When your device is not yet fully interviewed, this info will not yet be present. So make sure your device is interviewed at least once. Is the state of your device reported as ready and you still see Unknown Manufacturer, read on.

Z-Wave JS keeps a database of all devices it supports, including any special treatments they need. These are called the device configuration files and they are contributed mainly by the community. Is your device not fully supported, consider contributing the device configuration file.

I get a lot of sensor entities for my device that I’m probably never going to use

The integration will add as many useable entities for you as possible from the information it retrieves from your Z-Wave devices. Entities that you don’t want/like, can be disabled within the Home Assistant interface.

I renamed my devices in Z-Wave JS 2 MQTT but those names are not visible in Home Assistant

The names are only loaded when the Z-Wave JS integration is started. For Home Assistantto pick up those new names, either reload the integration or restart Home Assistant.

Troubleshooting Issues

Get a dump of the current network state

When trying to determine why something isn’t working as you expect, or when reporting an issue with the integration, it is helpful to know what Z-Wave JS sees as the current state of your Z-Wave network. To get a dump of your current network state, follow the menu:

Configuration -> Integrations -> Z-Wave JS -> Configure -> Download a dump of your network to help diagnose issues