How to Add Z-Wave Devices to Home Assistant

 

Introduction

Want to add a Z-Wave switch, sensor, lock, thermostat, or other device to Home Assistant? The basic process is simple: first, make sure Home Assistant has a working Z-Wave connection; then use the appropriate inclusion method to add your device to the network.

If you are starting from scratch, you will first need a compatible Z-Wave adapter. This guide explains the basic Home Assistant Z-Wave setup, how to choose an adapter, and the main steps for adding devices.  

SONOFF offers two Z-Wave adapter options for different setups: Dongle-PZG23 (USB Dongle Plus) for direct USB deployment, and Dongle-MZG23 (PoE Dongle Max) for more flexible USB or network-based deployment.  

 

1. What You Need Before Adding a Z-Wave Device

Before starting, make sure you have:  

● A working Home Assistant installation. Home Assistant OS is the recommended installation type for most users and supports the official Z-Wave JS app. If you use Home Assistant Container, you need to run a Z-Wave JS server separately.  

● A compatible Z-Wave adapter. This provides the radio connection to your Z-Wave network. You may also see this hardware referred to as a Z-Wave controller; USB models are often called dongles.  

● The Home Assistant Z-Wave integration and a Z-Wave JS server. For most Home Assistant OS users, the recommended setup is the Z-Wave integration + Z-Wave JS app.  

● A Z-Wave end device for your region. Z-Wave uses different radio frequencies in different regions, so check regional compatibility before buying.  

● The device manufacturer's instructions and security information. Keep its inclusion/exclusion instructions and any QR code, DSK, or PIN available during setup.  

Home Assistant software alone does not provide a Z-Wave radio. You need both compatible Z-Wave hardware and the software layer that connects the Z-Wave network to Home Assistant.  

👉 For the current requirements and setup options, see the Home Assistant Z-Wave integration documentation.

👉 For regional frequency details, see Home Assistant's guidance on setting the Z-Wave adapter's radio-frequency region.  

 

2. Choose a Z-Wave Adapter for Home Assistant

The main decision is where to place the Z-Wave adapter and how to connect it to Home Assistant.

● Choose USB if your Home Assistant host has an accessible USB port and allows suitable placement of the adapter.

● Consider a network-connected adapter if you want to position the radio separately from the host, particularly when the host is inside a metal cabinet or server rack.

SONOFF Dongle-PZG23: Simple USB Z-Wave Adapter

The SONOFF Dongle-PZG23 is a USB Z-Wave 800-series adapter based on the EFR32ZG23 chip.

It is a straightforward option for connecting a Z-Wave controller to your Home Assistant host through USB. The included USB extension cable lets you position the adapter away from the host and nearby USB equipment.

Placement matters: keep the radio away from metal enclosures and potential sources of interference, rather than choosing its location solely because a USB port is available. See the Z-Wave JS guidance on controller placement and interference for practical recommendations.

 

SONOFF Dongle-MZG23: Flexible USB or Network Deployment

The SONOFF Dongle-MZG23 (PoE Dongle Max) also uses the EFR32ZG23 Z-Wave chip and supports Ethernet, Wi-Fi, and USB connections.

Its network connection options are useful when you want to place the controller separately from the Home Assistant host. Choose a location with suitable network access and power.

For Ethernet deployment, use compatible PoE equipment to provide both data and power, or connect Ethernet for data and supply power separately through USB-C.

👉 Follow the Dongle-MZG23 power supply and connection guide for the supported arrangements.

The main advantage of network deployment is placement flexibility. The connection method alone does not guarantee better Z-Wave range, lower latency, or greater reliability.

Quick Comparison

● If your Home Assistant host already has a suitable location and an available USB port, Dongle-PZG23 offers a more straightforward setup.

● If adapter placement needs to be independent of the Home Assistant host, Dongle-MZG23 provides more deployment options. 

 

3. Ways to Connect a Z-Wave Adapter to Home Assistant

Home Assistant uses the Z-Wave integration to connect to a Z-Wave JS server, which communicates with your adapter. The arrangements below show how the server and device management can be deployed. For most beginners using Home Assistant OS, start with the first option.

For the recommended Home Assistant OS setup, follow the installation prompts to configure your controller. For product-specific instructions and other supported setups, see:

👉 Dongle-PZG23 Home Assistant setup guide

👉 Dongle-MZG23 Home Assistant setup guide

 

 

4. How to Add a Z-Wave Device to Home Assistant

Once your Z-Wave adapter and Z-Wave server are set up in Home Assistant, you can add individual Z-Wave devices to the network.

In Home Assistant:

1. Go to Settings → Connectivity → Z-Wave. 

2. Select Add device. Home Assistant will put the Z-Wave adapter into inclusion mode. 

3. Check whether your device supports SmartStart.

4. Follow the appropriate inclusion method:

• • SmartStart: With the device powered off, scan its Z-Wave QR code and follow the prompts. If offered, select Long Range or Mesh as appropriate. Power on the device and follow any additional manufacturer instructions.
  • Classic inclusion: Put the device into inclusion mode according to the manufacturer's instructions.

5. Complete any security prompt if required. For S2-secure inclusion, Home Assistant may ask for the PIN supplied with the device.  

6. Wait for Home Assistant to confirm that the device was added and for setup to complete, then check its available entities or events.  

👉 For the complete and current procedure, including SmartStart, S2 security, Long Range, and troubleshooting, follow Home Assistant's official guide to adding a new device to the Z-Wave network.

Note: Keep your Z-Wave controller in its normal location during inclusion, and start the process from Home Assistant's Z-Wave interface rather than from the controller itself.

After the Device Is Added

Once inclusion succeeds, Z-Wave JS interviews the device to identify its supported capabilities. Home Assistant then supports functions available through entities or events.

Battery-powered devices may need to be woken manually before the interview finishes.
After setup completes, test the functions you plan to use, such as switching an outlet, opening a contact sensor, checking a temperature reading, or triggering a button event.

👉 If a device appears in Home Assistant but some functions are missing, check Home Assistant's guidance on Z-Wave devices with missing or unavailable entities.

Moving a Z-Wave Device From Another Hub

A Z-Wave device cannot join a new network while it is still paired with another controller. If your device is still connected to a previous hub, exclude it from that network before adding it to Home Assistant.

If the original hub is available, use its exclusion process and follow the device manufacturer's instructions. If the original hub is no longer available, you can use Home Assistant's foreign-device exclusion process.

Start exclusion in Home Assistant first, then follow the manufacturer's instructions to put the device into exclusion mode. Once exclusion is complete, proceed with adding the device to your Home Assistant-controlled network.  

👉 For detailed instructions, see Home Assistant's guide to removing a device from a foreign Z-Wave network.

FAQs

Q1: Do I Need a Z-Wave Adapter for Home Assistant?

Yes. Home Assistant software does not include a Z-Wave radio, so you need a compatible Z-Wave adapter to communicate with Z-Wave devices.

If you're starting a new Z-Wave setup, Home Assistant recommends using an 800-series adapter with current firmware. The adapter works with Z-Wave JS and the Home Assistant Z-Wave integration to manage the network.

Q2: Can I Use a Zigbee Dongle for Z-Wave?

No. Zigbee and Z-Wave use different radio protocols, so a Zigbee-only dongle cannot act as a Z-Wave adapter.

Use hardware designed for Z-Wave instead. SONOFF currently offers two Z-Wave 800-series options: Dongle-PZG23 for USB deployment and Dongle-MZG23 for USB or network-based deployment. 

Q3: Will Any Z-Wave Device Work With Home Assistant?

Home Assistant and Z-Wave JS support many common Z-Wave devices, but support can vary by device and by the Z-Wave Command Classes it uses. A device may join the network successfully even if some manufacturer-specific features are not exposed in Home Assistant.

Before buying, also make sure the device uses the correct Z-Wave frequency for your region.

Q4: Why Does My Z-Wave Device Have No Entities in Home Assistant?

Entities are created after Z-Wave JS finishes interviewing the device. Battery-powered devices may need to be manually woken so the interview can complete.

Also, not every Z-Wave device creates standard entities. Some button remotes, for example, mainly generate events instead. If the interview has completed but expected entities are still missing, see Home Assistant's guidance on Z-Wave devices with missing entities.