This article may contain affiliate links. If you buy through these links, the price is the same for you and the store pays me a small commission that helps keep Tecnoyfoto running.
Z-Wave remains one of the most mature local protocols available for home automation, and Home Assistant now provides a much simpler way to build and manage a Z-Wave network than it did only a few years ago.
If you are starting from scratch in 2026, you no longer need to manually install the separate Z-Wave JS UI community app, configure WebSocket addresses, or generate security keys yourself. On Home Assistant OS, the recommended installation can handle almost all of this automatically.
In this updated guide, we’ll look at how Z-Wave works in Home Assistant today, which adapter makes sense for a new installation, how to set up your network, how to add devices securely, and how to troubleshoot the most common problems.
What is Z-Wave JS in Home Assistant?
Home Assistant uses the Z-Wave JS driver to communicate with Z-Wave devices.
A normal Z-Wave installation in Home Assistant consists of four main parts:
- Z-Wave adapter: the physical radio hardware that communicates with your Z-Wave devices.
- Z-Wave JS app: the server that communicates directly with the adapter and manages the Z-Wave network.
- Z-Wave integration: the Home Assistant integration that connects Home Assistant to the Z-Wave JS server.
- Z-Wave devices: sensors, switches, locks, plugs, thermostats, and other devices joined to your network.
The important point is that the Z-Wave JS app and the Z-Wave integration are not the same thing.
The app manages the Z-Wave network and communicates with the adapter. The integration connects that server to Home Assistant so your devices can appear as entities and be used in dashboards, scripts, scenes, and automations.
What Happened to Z-Wave JS UI?
This is one of the biggest changes compared with older Z-Wave guides.
For years, many Home Assistant users installed a separate community application called Z-Wave JS UI. It offered an advanced web interface for managing the Z-Wave network and was often recommended instead of the simpler official Z-Wave JS add-on.
That situation has changed.
The feature-rich Z-Wave JS UI interface is now included with the official Z-Wave JS app. Because of this, the separate Z-Wave JS UI community app is being phased out and Home Assistant recommends using the official Z-Wave JS app for new Home Assistant OS installations.
If you already use the separate Z-Wave JS UI app, your installation does not suddenly stop working. However, Home Assistant now provides a migration path to move to the official Z-Wave JS app without re-pairing all your devices.
Which Z-Wave Adapter Should You Buy in 2026?
If you are building a new Z-Wave network today, I would start with an 800-series adapter.
Home Assistant currently recommends the Home Assistant Connect ZWA-2, which is specifically designed to work with Home Assistant.
There are also other interesting 800-series options depending on your location, budget, and availability:
- SONOFF Z-Wave 800 Dongle Plus (Dongle-PZG23)Affiliate link: a conventional USB adapter based on the EFR32ZG23 800-series platform, with an external antenna and support for modern Z-Wave security and Z-Wave Long Range. It is an interesting option if you want a straightforward USB controller for Home Assistant.
- HomeSeer SmartStick G8: another established 800-series USB option.
- Zooz ZST39 800 Series Z-Wave Long Range S2 Stick: a popular alternative, particularly in North America.
SONOFF discount: If the SONOFF Dongle-PZG23 fits your installation, you can buy it from the official SONOFF store using this linkAffiliate link and use the coupon code tecnoyfoto to get 10% off.
Affiliate disclosure: the SONOFF link above is an affiliate link. If you purchase through it, Tecnoyfoto may receive a commission at no additional cost to you. This does not affect the technical criteria or recommendations in this article.
Older 500-series and many 700-series adapters can still work, so there is no reason to replace a stable existing installation simply because something newer exists.
However, for a new installation I would choose an 800-series controller and make sure its firmware is up to date.
Make Sure You Buy Devices for the Correct Region
Z-Wave does not use exactly the same radio frequencies everywhere in the world.
Your Z-Wave devices therefore need to match the region where they will be used.
With compatible 700- and 800-series adapters, Home Assistant can configure the adapter’s radio region. When using the official Z-Wave JS app, Home Assistant normally selects the appropriate region automatically according to the country configured in your Home Assistant system.
However, the frequency of the end devices themselves cannot simply be changed in software. Always buy Z-Wave devices designed for your region.
Installing Z-Wave in Home Assistant
For a normal Home Assistant OS installation, the setup is now considerably easier than older guides suggest.
Step 1: Connect the Z-Wave Adapter
Connect your supported Z-Wave adapter to the machine running Home Assistant.
Whenever possible, use a short USB extension cable instead of plugging the adapter directly into the computer.
USB ports and the computer itself can generate radio interference. Moving the Z-Wave adapter slightly away from the host can solve problems such as unreliable inclusion, delayed devices, failed secure inclusion, or apparently poor range.
A simple USB 2.0 extension cable is often enough.
Step 2: Let Home Assistant Discover the Adapter
Many Z-Wave adapters are automatically detected by Home Assistant.
When the discovery dialog appears, select:
Recommended installation
Home Assistant will then install the official Z-Wave JS app and configure the Z-Wave integration for you.
You do not normally need to:
- install Z-Wave JS UI manually,
- enter a serial port manually,
- create a WebSocket URL,
- or manually generate security keys.
What If Home Assistant Doesn’t Detect My Adapter?
If the adapter does not appear automatically:
- Go to Settings > Devices & services.
- Select Add integration.
- Search for Z-Wave.
- Follow the instructions shown by Home Assistant.
Also check that the adapter is properly connected and that any USB cable you are using supports data, not only power.
Step 3: Security Keys
Depending on your Home Assistant version and installation, you may be asked about Z-Wave security keys.
If this is a completely new Z-Wave network, leave the security-key fields empty and continue. Home Assistant will generate unique keys automatically.
If you are reusing an adapter that already contains securely paired devices, you must preserve the existing security keys. In particular, older securely included devices may require the original S0 key.
Once your network is configured, keep a backup of the security keys somewhere safe.
Adding Your First Z-Wave Device
Once the adapter and Z-Wave JS app are working:
- Go to Settings > Z-Wave.
- Select Add device.
- Follow the instructions for your Z-Wave device.
Home Assistant supports both traditional inclusion and SmartStart.
Using SmartStart
If your device supports SmartStart, look for a Z-Wave QR code on the product or its packaging.
From the Add device dialog, scan the QR code. Home Assistant can then prepare the device for inclusion before it is even powered on.
When the device is switched on and enters the network, it can be added automatically.
If the device also supports Z-Wave Long Range and your adapter and region allow it, Home Assistant may ask whether you want to add the device using Long Range or the traditional mesh network.
Classic Inclusion
For devices without SmartStart:
- Select Add device.
- Put the Z-Wave device into inclusion mode according to its manual.
- If S2 security is supported, Home Assistant may ask you for the device’s PIN.
- Wait until the interview completes and the entities are created.
Important: do not move the Z-Wave adapter around the house to include devices. Modern Z-Wave installations should normally add devices with the adapter in its permanent location. Moving the controller can result in routes that no longer represent the final installation.
Secure Inclusion: S2 vs S0
Z-Wave currently uses two main generations of security: S0 and S2.
Whenever possible, use S2.
S2 provides modern Z-Wave security without the large network-traffic penalty associated with S0.
S0 exists mainly for older devices that require secure communication but do not support S2, such as some older locks.
You should not force every device to use S0 simply because secure inclusion sounds better. S0 creates substantially more traffic on the Z-Wave mesh and can reduce network performance if used unnecessarily.
Home Assistant normally selects the most appropriate security method during inclusion.
The Z-Wave Control Panel in Home Assistant
One reason older tutorials recommended Z-Wave JS UI was that it provided tools that Home Assistant itself did not have.
That gap has become much smaller.
Go to Settings > Z-Wave to access the current Z-Wave control panel.
From here you can manage much more than just device inclusion.
Network Map
The Show map option displays a visual representation of your Z-Wave network and the routes being used between devices.
This can be useful when diagnosing range problems or understanding how your mesh has formed.
Network Statistics
Z-Wave JS collects communication statistics for the adapter and individual nodes.
These statistics can help identify communication problems, failed transmissions, excessive retries, and other RF issues.
Logs
The Z-Wave panel also provides access to Z-Wave JS logs.
Before guessing why a device is failing, checking the logs is often one of the most useful troubleshooting steps.
Network Backup
You can download a backup of the Z-Wave adapter’s non-volatile memory.
This backup contains the Z-Wave network information stored on the adapter, including the devices paired with it.
I strongly recommend creating a backup before:
- migrating to another adapter,
- resetting the adapter,
- or making major changes to the network.
Restore and Adapter Migration
Home Assistant can restore a compatible Z-Wave backup and also provides an adapter migration function.
This makes replacing a controller much easier than rebuilding the entire Z-Wave network from scratch.
Managing Individual Z-Wave Devices
Open a Z-Wave device in Home Assistant and use its device menu to access several useful maintenance tools.
Configure
This lets you view and change configuration parameters exposed by the Z-Wave device.
Re-interview
If a device has been included but some expected entities or capabilities are missing, you can force a new interview.
For battery-powered devices, remember that you may have to manually wake the device while the interview is taking place.
Rebuild Routes
If a mains-powered device is responding slowly or appears to have poor communication, rebuilding its routes can help Z-Wave JS discover a better path through the mesh.
Do not repeatedly rebuild routes without a reason. Route discovery creates substantial network traffic and should be used when troubleshooting an actual problem.
Firmware Update
If the device supports the Z-Wave firmware update mechanism, Home Assistant can install a firmware file supplied by the manufacturer.
Always make sure the firmware file is intended for the exact model and hardware revision of your device. Interrupting or installing the wrong firmware can damage the device.
Z-Wave JS UI Still Exists — Do I Need It?
For a normal Home Assistant OS installation in 2026, I would use the official Z-Wave JS app.
The separate Z-Wave JS UI community app is being phased out because its advanced user interface has now been incorporated into the official app.
There are still some advanced features that may appear first inside the Z-Wave JS UI interface included with the app before they are exposed directly in Home Assistant’s native Z-Wave panel.
For example, current versions of the official Z-Wave JS app provide additional access-control management for supported Z-Wave locks through the included Z-Wave JS UI.
So the distinction today is no longer:
“simple Z-Wave JS or advanced Z-Wave JS UI?”
For Home Assistant OS, the official Z-Wave JS app is now the normal choice and already includes the advanced UI.
What About Home Assistant Container?
The recommended installation described above applies to Home Assistant OS, where Home Assistant can install and manage the Z-Wave JS app for you.
If you run Home Assistant Container, there is no Home Assistant app system managing the Z-Wave server.
In that case you must run a compatible Z-Wave JS server separately.
One common option is the Z-Wave JS UI Docker container. The Home Assistant Z-Wave integration then connects to that server using WebSockets.
This is one of the situations where manually entering a Z-Wave JS server address is still appropriate.
Migrating from the Separate Z-Wave JS UI App
This procedure is for Home Assistant OS installations that already use the separate Z-Wave JS UI community app. Do not simply stop and uninstall it and then start the official app. Its data must be migrated first so that the server configuration, security keys, and the information Home Assistant needs to recognize the existing network are preserved.
Important: do not reset the adapter, exclude any devices, or uninstall Z-Wave JS UI yet. A correct migration does not require you to re-pair the network.
Before you begin
- Create a full Home Assistant backup and download it to another device.
- Keep a separate copy of your Z-Wave security keys, especially the S0 key if older devices were securely included.
- Make sure you have administrator rights.
- Choose a time when the Z-Wave network can be temporarily unavailable.
Step 1: Install the official app and the helper apps
- Go to Settings > Apps > Z-Wave JS and install the official app.
- Do not start it yet. Two servers must not try to use the same adapter at the same time.
- Install Terminal & SSH and an app that can upload files, such as File editor or Studio Code Server.
Step 2: Download the Z-Wave JS UI backup
- Open the web interface of the separate Z-Wave JS UI community app.
- Open the Store tab and select Download in the bottom-right corner to save its ZIP backup.
- Keep a copy of that ZIP on your computer.
- Stop Z-Wave JS UI, but leave it installed until the migration has been verified.
Step 3: Run the official migration script
The official Home Assistant documentation links to the migration script that prepares the data for the new app.
- Download the script ZIP from the link in the official documentation and extract
migrate_to_zwave_js_app.sh. - Upload the script and the Store backup ZIP to a temporary Home Assistant folder, preferably
/tmp. - Open the terminal and run the following commands, replacing the example filename with the name of your backup:
cd /tmp
chmod +x ./migrate_to_zwave_js_app.sh
./migrate_to_zwave_js_app.sh store-backup_YYYYMMDDHHMMSS.zipFollow the prompts shown by the script. If it reports an error, stop and preserve the existing installation. Do not reset the adapter or try to rebuild the network manually.
Step 4: Reconnect the Z-Wave integration
- Go to Settings > Devices & services > Z-Wave.
- Open the three-dot menu, select Reconfigure, and then choose Reconfigure the current adapter.
- For a normal USB- or TCP-based controller, select Use the Z-Wave Supervisor app, choose the controller, and submit.
- If you use a GPIO module or the controller is not listed, clear that option and enter
ws://core-zwave-js:3000manually.
Step 5: Verify the migration before removing the old app
- Start the official Z-Wave JS app if Home Assistant has not started it automatically.
- Confirm that the same nodes, devices, and entities are present.
- Test several mains-powered devices and at least one battery-powered device.
- Open the advanced interface included with the official app and confirm that the network is displayed correctly.
- Once everything works, uninstall the old community app and remove the ZIP and script from the temporary folder.
The Z-Wave mesh remains stored in the adapter, so this procedure changes the server that manages it rather than rebuilding the network. If your separate Z-Wave JS UI setup is stable, you can prepare the migration carefully; the important part is to follow the migration path instead of directly replacing one app with the other.
Home Assistant Z-Wave Troubleshooting
My Device Won’t Pair
If a device refuses to join:
- Check that the device and adapter use the correct Z-Wave region.
- Try excluding the device first, even if you don’t think it is currently paired.
- Factory reset the device if necessary.
- Check the manufacturer’s inclusion procedure.
- Make sure the Z-Wave adapter is using a USB extension cable and is away from interference.
Do not immediately move the controller next to the device. Keeping the adapter in its normal location produces a network that better represents how it will actually operate.
The Device Was Added but Some Entities Are Missing
The most common reason is an incomplete interview.
Battery-powered Z-Wave devices spend most of their time asleep. Wake the device manually according to its manual and then use Re-interview from the device page.
Also remember that some Z-Wave devices, particularly certain buttons and remote controls, may expose events instead of normal entities.
A Device Is Slow or Unreliable
Before replacing hardware, check:
- Z-Wave statistics,
- the network map,
- Z-Wave JS logs,
- USB interference,
- and the routes being used by the device.
If the device has been moved or the mesh topology has changed substantially, a route rebuild may help.
Should I Poll Z-Wave Devices?
Only when there is a real need.
Z-Wave is a relatively low-bandwidth network. Constant polling can generate unnecessary traffic and make the whole network slower.
Modern Z-Wave Plus devices normally report their state automatically.
If an older device does not report changes properly, Home Assistant provides ways to refresh individual values, but polling should be treated as a workaround rather than something to enable everywhere.
Z-Wave or Zigbee: Which Is Better?
Neither protocol is automatically better for every house.
Z-Wave uses region-specific sub-GHz frequencies, which keeps it away from the crowded 2.4 GHz band used by Wi-Fi and most Zigbee networks.
Zigbee, on the other hand, generally offers a much larger selection of inexpensive devices.
Both can build reliable local mesh networks when they are designed correctly.
For many Home Assistant installations, using both protocols makes perfect sense: choose the device and protocol that best solve each problem instead of trying to make the whole house use one technology.
Frequently Asked Questions
Is Z-Wave JS an integration or an app?
Both names appear because different components are involved.
Z-Wave JS is the underlying open-source driver.
The Z-Wave JS app runs the Z-Wave server on Home Assistant OS.
The Z-Wave integration connects Home Assistant to that server.
This separation is normal and is part of the current Home Assistant architecture.
Do I need to install Z-Wave JS UI separately?
Not for a normal new Home Assistant OS installation.
The official Z-Wave JS app now includes the feature-rich Z-Wave JS UI, and the separate community app is being phased out.
Do I need to manually configure a WebSocket URL?
Not when using the recommended Home Assistant OS installation.
Home Assistant configures the connection automatically.
A manual WebSocket URL is mainly relevant if you run your own Z-Wave JS server, use Z-Wave JS UI separately, or run Home Assistant Container.
Should I generate the Z-Wave security keys manually?
For a completely new network, no.
Leave the fields empty during the normal setup and Home Assistant will generate unique keys for you.
Existing networks are different: if your adapter already has securely paired devices, preserve the security keys that were originally used.
Should I buy a 700-series or 800-series adapter?
For a new installation, I would choose an 800-series adapter.
If an existing 500- or 700-series network is working reliably, however, there is no reason to replace the adapter simply to have a newer generation.
Is the SONOFF Dongle-PZG23 a good option for Home Assistant?
It is an interesting 800-series USB option for a conventional Home Assistant Z-Wave installation.
The SONOFF Z-Wave 800 Dongle Plus (Dongle-PZG23) uses an 800-series EFR32ZG23 platform, includes an external antenna, and is designed to work with Z-Wave JS-based systems.
Home Assistant’s own officially recommended adapter remains the Home Assistant Connect ZWA-2, so I would not describe the SONOFF as the official Home Assistant recommendation. However, it is a perfectly reasonable alternative to consider when choosing an 800-series USB controller.
If you want to buy the SONOFF Dongle-PZG23 from the official SONOFF storeAffiliate link, the coupon code tecnoyfoto gives you 10% off.
Do I need to repair my whole network after moving to the official Z-Wave JS app?
No.
The Z-Wave network itself is stored in the adapter. Migrating from the separate Z-Wave JS UI app to the official Z-Wave JS app does not require you to exclude and re-add every device when the migration is performed correctly.
Conclusion
In 2026, there are two different paths depending on where you are starting:
If you are creating a new Home Assistant OS network
- Connect a supported Z-Wave adapter.
- Select the recommended installation.
- Let Home Assistant install and configure the official Z-Wave JS app.
- Add devices from Settings > Z-Wave.
If you already use the Z-Wave JS UI community app
Do not replace it directly or re-pair your devices. Download its Store backup, run the official migration script, and reconfigure the integration to use the official app, as described in the migration section above.
The advanced Z-Wave JS UI tools have not disappeared; they are now included in the official app. The result is a simpler setup for a new network and a safe migration path for existing installations.