Set up Z-Wave in Home Assistant

  • Dustin Casto
  • December 7, 2021 (Updated: December 14, 2021)

Once you have a fresh Home Assistant installation up and running, you will likely want to dive into configuring your smart home devices. Before you can do any automation or control any smart devices, you must do some initial configuration before the fun can begin. Fortunately, the Z-Wave integration in Home Assistant has been greatly improved recently. Home Assistant is on its third Z-Wave add-on so hopefully the third time is a charm and the Z-Wave integration will continue to be well supported going forward. I feel that it is important to Home Assistant’s success to have solid support for the major smart home protocols such as Z-Wave.

Purchase a USB Z-Wave Device

Before continuing this guide, you will need to have purchased a Z-Wave USB device that will act as the centralized Z-Wave hub for your network. Since Home Assistant is a DIY smart home solution, purchasing a dedicated Z-Wave hub such as SmartThings (affiliate link) is not necessary. Instead, you will need to use a dedicated system such as a Raspberry Pi, the official Home Assistant hub, or some other computer system. You may even run Home Assistant in a virtual machine on a server running on your network.

I personally have used both the Aeotec Gen5+ (affiliate link) and the Zooz 700 Series USB (affiliate link) devices. I decided to get the Zooz to take advantage of the 700 series features (better range, lower power consumption, etc), and the Aeotec was not available to purchase at the time (also, I wanted to have an extra Z-Wave controller to use to write these guides so I am not messing around with my main Home Assistant setup). The Zooz is also more affordable so I thought I would give it a try. Raspberry Pi users have the option of a Z-Wave hat rather than using a USB stick which may be more desireable if putting everything inside an enclosure.

Plug in the USB Stick and Identify the Hardware ID

It should go without saying but the USB stick needs to be plugged into the device you are using as the Home Assistant/Z-Wave hub. Once it is plugged in, you will need to determine the hardware ID for the device so that you can enter that information into the Z-Wave add-on.

Click on the “Configuration” menu and then “Add-ons, Backups & Supervisor”.

Check Hardware ID

You will need to click on the “System” tab at the top of the page to show all of the system information. Under the “Host” section, click on the icon with the 3 dots to select the “Hardware” menu option.

Check Hardware ID

Depending on the hardware you have installed, it should be immediately apparent which device is your USB Z-Wave controller. My Zooz 700 series shows up as a USB device with a very long ID. Fortunately, for the Z-Wave JS add-on, you do not need to type the ID nor copy/paste it. However, for the Z-Wave JS to MQTT add-on, you will need to copy/paste the hardware ID for the Z-Wave controller.

Check Hardware ID

(Optional) Pass through the USB Device to your Virtual Machine in Proxmox

If you are using a virtual machine in Proxmox for Home Assistant like I am, you will have the extra step of passing through the USB device before you can see the hardware ID of your USB device. This process will vary among different hypervisors/virtual machine managers if you are not using Proxmox.

Proxmox USB Passthrough

Choose a Z-Wave Add-on to Install

There are two Z-Wave add-ons for Home Assistant: Z-Wave JS and Z-Wave JS to MQTT. The Z-Wave JS is an officially supported add-on while Z-Wave JS to MQTT is a community add-on. At a high level, Z-Wave JS provides the standard options for Z-Wave support while Z-Wave JS to MQTT exposes more options and includes a feature rich control panel. More advanced users may prefer the Z-Wave JS to MQTT add-on. I will cover both so you can decide which will serve your needs the best.

The supervised version of Home Assistant has a built-in add-on store, which makes installing add-on’s very simple. I will assume you are using the supervised version for this guide. If you are not using the supervised verison, you will have to set up the Docker container manually.

Add-on #1: Install the Z-Wave JS Add-on

To install the Z-Wave JS add-on, go to the “Configuration > Add-ons, Backups & Supervisor” page.

Install Z-Wave JS Add-on

Click on the “Add-on Store” button.

Install Z-Wave JS Add-on

Find the Z-Wave JS add-on and click on it.

Install Z-Wave JS Add-on

Simply click the “Install” button.

Install Z-Wave JS Add-on

After the add-on is installed, go to the “Configuration” tab which will be displayed above the current Z-Wave JS add-on page. You will need to select the USB device for your Z-Wave controller. Fortunately, you do not need to type or copy/paste the device as it will be displayed automatically. Leave all of the authentication keys blank since they will be generated automatically when you start the Z-Wave add-on. Click the “Save” button.

Install Z-Wave JS Add-on

Go back to the “Info” tab. You will want to make sure the add-on starts on boot and enabling the watchdog is also a good idea so the add-on can be restarted automatically if it crashes. Click the “Start” button to load the add-on.

Install Z-Wave JS Add-on

To verify that the security keys are automatically generated, go to the “Configuration” tab. You should be able to see the generated keys. It is possible you may need to refresh the page in order for it show all the values. If you desire, you can add your security keys manually instead of using the generated keys, but you will have to make sure they are generated in the proper format.

Install Z-Wave JS Add-on

Configure the Z-Wave JS Integration

Even though you installed and configured the Z-Wave add-on, you will need to configure the Z-Wave integration. This step is not immediately intuitive since I assumed installing the add-on would be enough. The integration is necessary so that you can add/remove devices from your Z-Wave network. Also once the devices are added, they will show up automatically in the default “Overview” dashboard page.

Go to the “Integrations” tab on the “Configuration > Devices & Services” page to configure the Z-Wave integration.

Configure Z-Wave JS Integration

There will be a “Configure” button you will need to click to get started with the integration.

Important: Before you can configure the Z-Wave integration, you may need to reboot Home Assistant after you finish configuring the Z-Wave JS add-on. I noticed that it would not show up on the “Integration” page as a “Discovered” integration until I rebooted. Instead of rebooting Home Assistant if Z-Wave JS is not immediately discovered, you may click on the “Add Integration” button at the bottom corner of the page and search for “Z-Wave JS” to install the integration.

Configure Z-Wave JS Integration

Click “Submit” to get started with the configuration.

Configure Z-Wave JS Integration

The only thing you need to configure is the “Area” where your USB Z-Wave device is located. You can create custom locations like I have in the screenshot below. It is useful to create meaningful and descriptive areas because it helps group your devices on the default “Overview” dashboard. Click “Finish” to complete the configuration.

Configure Z-Wave JS Integration

You will see that the integration no longer shows as “Discovered” and is installed along with the “Supervisor” integration (if you are running the supervised version of Home Assistant).

Configure Z-Wave JS Integration

Include a New Z-Wave Device on Your Z-Wave Network

With the Z-Wave JS add-on and the Z-Wave integration set up, you can now finally add any Z-Wave device of your choice! For my example, I am going to include a Zooz ZEN15 power switch. Since it is nearing Christmas, I bought the Zooz power switch cord to turn on/off Christmas lights (the power cord will be located under a covered porch) so it provided me the perfect opportunity to demonstrate how to add a device to a Z-Wave network.

On the “Integrations” tab on the “Configuration > Devices & Services” page, click on the “Configure” button for the Z-Wave JS integration.

Add Z-Wave Device

Next, click “Add Device” to start the process of adding a new Z-Wave device to your network.

Add Z-Wave Device

While in “inclusion mode”, you need to push a button or a sequence of pushes/buttons to add the device to your network. This can vary between Z-Wave devices so you should definitely consult the manual so you know what to do. Some devices have a different method for inclusion for secure and non-secure connections. For the Zooz ZEN15, I have to push and hold the button on the power cord for 3 seconds to add it to the network.

There is also an option for a QR code if you are on a device which can scan a code.

Add Z-Wave Device

If all goes well, you should see the device successfully added to your network!

Add Z-Wave Device

You may now skip the “Add-on #2” section to continue this guide if you chose this option.

Add-on #2: Install the Z-Wave JS to MQTT Add-on

If you chose to install the Z-Wave JS to MQTT add-on instead of Z-Wave JS, go to the “Configuration > Add-ons, Backups & Supervisor” page. Click on the “Add-on Store” button. Find the Z-Wave JS to MQTT add-on in the “Community Add-ons” section and click on it.

Install Z-Wave JS to MQTT Add-on

Click “Install” to get started.

Install Z-Wave JS to MQTT Add-on

You will likely want to enable all the options for starting on boot, the watchdog, and show in sidebar to get the best experience. That way Z-Wave JS to MQTT is started automatically when you reboot, restarts when it crashes, and exposes the feature rich control panel. Click the “Start” button to start Z-Wave JS to MQTT process.

Install Z-Wave JS to MQTT Add-on

This step is very important. You need to go to the “Configuration” tab for the add-on and enter the default port 3000 in the “Host” field as shown in the screenshot. You could use another port but since it is only being used locally for a single instance of Z-Wave, the default value is fine to use.

Install Z-Wave JS to MQTT Add-on

If you started the add-on prior to this step as I have recommended, you will be prompted to restart the add-on. You could set the port value before starting the service and you would not receive this prompt. However, you would have to jump back to the add-on page to start Z-Wave JS to MQTT service so it is less pages to navigate if you start it first.

Install Z-Wave JS to MQTT Add-on

Now you need to go to the “Z-Wave JS” page by clicking the sidebar menu. You can choose if you wish to submit statistics to help the Z-Wave JS project. If you enjoy helping out a development community, you may wish to enable this feature. It is designed to be secure and anonymous.

Install Z-Wave JS to MQTT Add-on

You have arrived at the default page of the Z-Wave JS to MQTT Control Panel. At the moment, there are no devices listed since you are not finished setting up the add-on. Click on the “Control Panel” menu icon.

Install Z-Wave JS to MQTT Add-on

The menu will slide out to expose all the menu options. Click on the “Settings” menu option.

Install Z-Wave JS to MQTT Add-on

If you remember the check hardware ID step, you will need to copy/paste the hardware ID into the “Serial Port” field. If you use the dropdown, you will likely see an option for /dev/ttyUSB0 which may be your USB Z-Wave device, but it is often recommended to use the full hardware ID because the generic ID of /dev/ttyUSB0 could in theory change.

Install Z-Wave JS to MQTT Add-on

Configure the Z-Wave JS Integration

Just like with the Z-Wave JS add-on, you will need to install the Z-Wave JS integration. The difference this time is that the Z-Wave backend will be controlled with the more feature rich Z-Wave JS to MQTT control panel. For this step, it is very important to click on the “Add Integration” button rather than using the “Discovered” integrations to ensure proper setup of the integration.

I noticed during my installation of the Z-Wave JS integration for Z-Wave JS to MQTT is that the “Integrations” page shows both “Z-Wave JS” and “CP2102N USB to UART Bridge” as discovered integrations (you may not see both of these immediately unless you reboot Home Assistant). Picking either one of those does not seem to prompt for the location of the Z-Wave JS to MQTT backend. I was able to get the discovered Z-Wave JS integration to show the prompt once but when I was playing around with grabbing screenshots for this guide, it no longer prompted for it. However, it seems like selecting it from the “Add Integration” box works properly in a consistent manner.

Click the “Add Integration” button on the “Integrations” tab on the “Configuration > Devices & Services” page to configure the Z-Wave integration to connect with the Z-Wave JS to MQTT add-on.

Configure Z-Wave JS Integration

Search for “Z-Wave JS” to find the Z-Wave JS integration more quickly (otherwise you have to scroll to the bottom of a long list of integrations).

Configure Z-Wave JS Integration

Although you may have 1 or 2 other Z-Wave integrations discovered, click on “No, set up another instance of Z-Wave JS”. This needs to be done so you can connect to the Z-Wave JS to MQTT backend. Do not worry, once the integration is installed the other discovered Z-Wave integration(s) will automatically be removed since you will have the Z-Wave JS integration fully configured.

Configure Z-Wave JS Integration

You must uncheck the box which prompts “Use the Z-Wave JS Supervisor add-on” because it will try to install the Z-Wave JS add-on which is not desirable when wanting to use Z-Wave JS to MQTT. Click “Submit” to continue.

Configure Z-Wave JS Integration

When installing the Z-Wave integration for the Z-Wave JS to MQTT add-on, you will be prompted for the websocket address of the Z-Wave JS to MQTT service. In one of the steps of installing the Z-Wave JS to MQTT, the port number had to be set in order to enable the websocket to be enabled. The default value is 3000 so if you use the default port number, you should be able to click “Submit” without changing any values. It is important that you have enabled the websocket port in the Z-Wave JS to MQTT control panel before setting up this integration.

Configure Z-Wave JS Integration

If all goes well, you will be presented with a list of devices that are found. Right now it should only be your USB Z-Wave device, but if you have other devices already associated to your USB Z-Wave device, they will also be listed. Enter a location for your USB Z-Wave controller. You may enter custom locations like I have in this example. Click “Finish” to finish setting up the Z-Wave JS integration.

Configure Z-Wave JS Integration

Navigate to the “Z-Wave JS” menu on the left sidebar to open the default page of the “Control Panel”. You should see your USB Z-Wave controller listed. You are now ready to add devices to your Z-Wave network!

Configure Z-Wave JS Integration

Include a New Z-Wave Device on Your Z-Wave Network

Including devices on your Z-Wave network is a similar but different process than with the Z-Wave JS add-on. You need to go to the “Z-Wave JS” page and click on the “Actions” menu.

Add Z-Wave Device

You will see the “Manage Nodes” and “Advanced” buttons appear. Click on “Manage Nodes”.

Add Z-Wave Device

To include a device, you will need to start the “Inclusion” process. It should be the default option selected. Simply click “Next”.

Add Z-Wave Device

Z-Wave JS to MQTT gives you more options during the inclusion process for encryption and for scanning QR codes. If you are on a desktop PC, using a QR code may not be the easy to do unless you have a webcam. Using the “Default” option in most cases may be fine for your needs unless you have reasons for using the others. Click “Next” to start the inclusion process.

Add Z-Wave Device

There will be a 30 second timer that will start. You will need to push the proper sequence of button(s) on your device to have it included in the Z-Wave network.

Add Z-Wave Device

When the device has been added, you will see the success page. For some reason, my Zooz power switch did not use S2 security so it defaulted to “None” when I closed out the box. I am not entirely worried about security on a power switch that controls my Christmas lights. Also, I do not think I have malicious neighbors or creepy stalkers outside my house looking to hack my Z-Wave network (I have cameras outside that I can watch for that). I would be most concerned to have security enabled for door locks and those sorts of Z-Wave devices.

Add Z-Wave Device

You should now see the new device in the list of Z-Wave devices!

Add Z-Wave Device

The Z-Wave JS to MQTT configuration was a bit more involved, but you gain a lot more features which may be valuable to you.

View the Device on the Default Dashboard

With the Z-Wave add-on of your choice installed, the Z-Wave integration configured, and your first device added, you will be able to see the entities created for the device when you go to the default “Overview” dashboard page. At this point you can turn on/off the device, view sensor values, etc. depending on the capabilities of your device. For the Zooz power switch, you can see there is an option to turn it on/off and to view the power consumption since the switch has energy monitoring capabilities. You will notice that the switch and the sensors are grouped into two separate sections based on the types of the entities (switches, sensors, etc.). If you add the device to an “Area”, then the switch/sensors will appear in the same group by area name instead of by entity type.

To test if your Z-Wave add-on/integration is functioning properly with your Z-Wave device, you may click the toggle button for on/off to turn your switch or other device on/off. There is nothing like testing out your devices such as light switches for the first time because it is fun to see everything turn on/off with a push of a button or via an automation.

Home Assistant Overview Page

Create Automations and Scenes

Home automation shines when you start creating various automations and scenes. To take full advantage of Home Assistant, you will want to create various automations and scenes. However, that is a topic on its own, which I will cover later. As you get more comfortable creating automations, you will find yourself digging deeper into powerful features to create more intricate automations.


comments powered by Disqus

Related Posts

How to Install Home Assistant on Proxmox

  • November 11, 2021

Home Assistant is a home automation software that is often installed on single board computers (SBCs) such as the Raspberry Pi because the system resources required by Home Assistant are low enough that a SBC will be sufficient for many users.

Read more

How to Put Home Assistant behind Existing Nginx Proxy Manager

  • May 12, 2022

A reverse proxy allows you to conveniently have a single entry point by which you may host multiple apps/services on one or more systems.

Read more

Add the Community Add-on Repository in Home Assistant if it is not Installed

  • March 15, 2022

When I was updating the Home Assistant Core, I encountered an interesting issue. It broke my Z-Wave JS to MQTT add-on.

Read more