I am trying to install the unofficial version of the Z-wave integration after I installed the Z-wave JS UI add-on. I was able to pair 3 Aeotec Smart Switch 7’s into the UI, My processor is a Home Assistant Green running the latest OS and core. I am following the documentation in the Z-wave JS UI. have tried both the ws://a0d7b954-zwavejs2mqtt:3000 and ws://localhost:3000 url’s. I unchecked the correct box. I get success from local host but also fail to load. Restarting HA does not correct the situation. So why doesn’t it work.
There is no unofficial version of the Z-wave integration. The same “official” integration is used for both add-ons.
Post a picture of your Z-wave JS UI settings page, the “Home Assistant” section. Maybe we can figure it out.
Zwavejs and ZwavejsUI are pretty much same
Zwavejsui, as name implies, just adds a ui.
If you plan to switch from one to other, uninstall the one. Very common for people to do what you seem to be attempting only to have it fail a few months later because bother are installed.
If an “unofficial” version did exist, why would you think it would be better than official?
This is where I am starting, from the Z-Wave JS UI docs, my comments in italic.Its my undertanding that the official is Ver. 0.17 while the other is 10.something
Now it is time to set up Home Assistant:
- Go to the Settings panel and click “Devices & Services”.
- In the bottom right, click “+ Add Integration”.
- Select the “Z-Wave” integration from the list.
- A dialog box will show, asking to use the add-on:
o UNCHECK that box, or else it will install the unofficial add-on.
o Again, the official add-on is the recommended installation, not the custom one, so… - In the next dialog it will ask for the server. Enter:
ws://a0d7b954-zwavejs2mqtt:3000
or ws://localhost:3000 - Confirm and done! Not so fast, restart HA
I would be happy to have only Z-Wave JS UI ,if I could access the devices from automations, but they don’t show up anywhere outside the UI version on the control panel. I will post images soon
No clue what docs you got that from. Even zwavejsui docs, which is what that appears to be from, says “uncheck…or it will install OFFICIAL add-on”
As long as you have zwavejs or zwavejsui addon installed you should be OK.
didnt realize this before but zwavejs is official addon and zwavejsui is community (unofficial maybe?) addon. Both are fine. I dont use either but would lean toward zwavejs(offical) since I try to avoid third party software as much as possible.
You absolutely cannot have both seperately installed.
so in homeassistant >> settings >> devices and services >> zwave
What do you see?
the instructions, which I added italics to, are in the documentation tab of the Z-WAVE JS UI addon http://homeassistant.local:8123/hassio/addon/a0d7b954_zwavejs2mqtt/documentation
The naming of these components is unfortunately confusing, but it’s critical to get this right. For Z-Wave to work correctly:
- The Integration “Z-Wave” must be running (Settings → Devices & Services → Integrations)
- One and only one of the Add-on’s must be running, either “Z-Wave JS” or “Z-Wave JS UI” (Settings → Add-ons)
[/grid]
this is part A the UI section, part B and the home assistant section to follow.
I am going to checj USB port assignments one more time. I also have a Zigbee stick that worked well. The USB port names seem long and are never exactly what the docs say
this is part B the UI section, part A previously
and the home assistant section to follow.
I am going to check USB port assignments one more time. I also have a Zigbee stick that worked well. The USB port names seem long and are never exactly what the docs say
this is the home assistant section parts A and B of the UI section, were previously sent / posted.
I am going to checjk
USB port assignments one more time. I also have a Zigbee stick that worked well. The USB port names seem long and are never exactly what the docs say
First, there’s no reason to expose port 3000 in the add-on Network settings (and the add-on instructions never tell you to do this). That is never needed unless you have a very unusual configuration with two separate instances of HAOS. So you can remove that unless you are OK with the Z-Wave JS server exposed to anything on your local network with no authentication or encryption.
Second, server URL ws://locahost:3000 is incorrect in this case. As the instructions for the ZUI add-on state explicitly, the URL is ws://a0d7b954-zwavejs2mqtt:3000 (always for everyone using the add-on). If HA is not connecting with that address, then there is a misconfiguration of the Z-Wave JS UI settings or it has failed to start due to some error. Perhaps you should show screenshots of your configuration settings (don’t expose the security keys) in Z-Wave JS UI. Then also look at the add-on logs and post if necesssary. Make sure you have not changed anything in the Home Assistant settings panel of ZUI.
Yeah, it’s very unfortunate (and apparently confusing) that the docs mention “official” at all. But, I’m not clear why you modifed the instructions. The actual text is this screenshot:
Yes, the wording is confusing:
- UNCHECK that box, it will install the official add-on.
… is really saying uncheck OR ELSE it will install the “official” add-on.
And why those docs say “Again, the official add-on is recommended, so…” just adds more confusion, IMO, and seems out of place considering those docs are for installing the UI version.
The USB paths are not the same for everyone, unlike the websocket address. Mine shows this, for example:
But, you said you can see your devices in the z-wave-js ui, so that means that is configured correctly.
BTW, reguarding that websocket address; When Home Assistant runs add-ons, which are just containers managed by HA, it sets up a “private” network that allow add-onss to talk to each other, but not expose those ports to the outside world.
If I ssh into the ssh (add-on) container I can ping the zui add-on:
bill@whm4pro ~ $ ssh ha
...
➜ ~ ping a0d7b954-zwavejs2mqtt
PING a0d7b954-zwavejs2mqtt (172.30.33.1): 56 data bytes
64 bytes from 172.30.33.1: seq=0 ttl=64 time=0.108 ms
64 bytes from 172.30.33.1: seq=1 ttl=64 time=0.232 ms
^C
But if I ssh into the operating system I cannot:
bill@whm4pro ~ $ ssh haos
Welcome to Home Assistant OS.
Use `ha` to access the Home Assistant CLI.
# ping a0d7b954-zwavejs2mqtt
ping: bad address 'a0d7b954-zwavejs2mqtt'
The point being is you configure the integration to talk to the websocket provided by the ZUI add-on exactly as the documentation says.
IMO, we might be better off if the integration didn’t provide an option to start the “official” add-on, but rather made people pick which add-on to use. (Is there a reason to not set up ZUI for eveyone?)
1 Like
When I submitted my original post I included the instructions with my interpretations , i.e. " or else " in italics. As far as the websocket address, the first option that is presented is “localhost”. I have tried both options, localhost and the expanded one. Neither one loaded the Z-wave integration. The question seems to be, why is the integration not loading. As I write this I realize there are confusing terms all over.
integration: I think of that more as bringing in things like Lutron
for integration: Z-Wave versus Z-Wave JS
uncheck the box: the box is labeled use the Z-Wave Supervisor add-on
for integration: Z-Wave versus Z-Wave JS
No, there is only Z-Wave (In 2021 there were two, only Z-Wave since then).
Integrations vs. Add-ons:
1 Like
Agreed, if you haven’t familiarized yourself. The documentation lays it out pretty clearly.
The way I look at it, integrations convert vendor defined data structures into data structures that are native to Home Assistant. They are simply a data translator that structures data for the Home Assistant state machine to use internally. Integrations generally talk to devices using a local or cloud API that follow a known structure and are usually IP based. That’s great as Home Assistant speaks TCP/IP directly. An integration is just a self contained sub-component of Home Assistant that runs in the same docker container.
Some devices, however, don’t offer an easy IP-based API. Z-wave and ZigBee are good examples. The hardware controllers and coordinators frequently have a serial API with the need for a low-level driver.
Home Assistant chose to solve this architecture challenge by using Add-ons. As previously pointed out, an Add-on is separate docker container running a specialized application. In both the case of the Official Z-wave Add-on and Z-wave-JS UI Add-on, these applications talk to the serial port of the device and use the Z-wave-JS driver to convert to an IP-based WebSocket server. In the case of the UI Add-on, it also adds a web-based user interface.
Now the Z-wave integration has an IP-based API it can talk to for it’s data conversions. If it throws an error, it’s a problem communicating with the Add-on, which as pointed out, could simply be the Add-on is failing due to a configuration problem.
Check the Add-on logs for errors. Make sure both Add-ons aren’t installed. Check Home Assistant logs for integration errors that may have a clue.
Plenty of good info here, so maybe nothing needs to be added. But, coffee…
I found it all very confusing[1] when first setting things up, and getting a grasp of how the parts work together really helps, IMO.
You mentioned that you can see your devices in ZUI, so it looks something like this, right?
Then you know z-wave-js-ui is working and communicating with your stick. You DO want to make sure there’s not another add-on talking to the same controller device, of course.
Next, make sure ZUI is configured to use websockets at the bottom of this part of the config:
If you want't to check...
If you happen to have the Advanced SSH add-on installed, I suppose you could check if the z-wave websocket port is open…
➜ ~ nmap -p 3000 a0d7b954-zwavejs2mqtt
Starting Nmap 7.95 ( https://nmap.org ) at 2025-06-28 10:13 PDT
Nmap scan report for a0d7b954-zwavejs2mqtt (172.30.33.1)
Host is up (0.00023s latency).
PORT STATE SERVICE
3000/tcp open ppp
MAC Address: FE:84:19:F1:FA:F2 (Unknown)
Nmap done: 1 IP address (1 host up) scanned in 0.37 seconds
Then the integration (the code in Home Assistatant that talks to ZUI via a websocket) needs to be configured to talk to that open websocket.
If it is configure incorrectly like this I see:
(FYI – oddly! nothing was loged in home-assistant.log about it failing to connect.)
And that’s all the parts.
IF the integration successfully connects AND then devices do not show up in HA then it’s time to enable debugging and watch (and post) home assistant logs related to z-wave.
More TMI
if curious about “official” vs the other one, you can look at the “official” dockerfile that builds the docker image (based on versions here), where the UI version’s docker file is here, which is a tarball of the, well, official packaged up ZUI. And then look at the ZUI page to see what version of z-wave-js in in that package.
[1] not that I’m not often confused
I’ve now verified that the Z-Wave JS UI add-on is running properly (v4.5.0), but the Z-Wave JS integration tile still doesn’t appear under Settings → Devices & Services. The core is 2025.6.3
Here’s what I’ve done so far:
- Clean configuration.yaml (Z-Wave lines commented out)
- Verified WebSocket URI is ws://a0d7b954-zwavejs2mqtt:3000
- Reinstalled and restarted the Z-Wave JS UI add-on multiple times
- Used File Editor, SSH, and the Terminal to confirm folders, config files, .storage contents
- Restarted the core and even rebuilt it using the CLI
- Validated configuration (no errors), checked logs, and made sure there are no pending repairs
I’ve reviewed everything I can think of and still can’t get the Z-Wave JS integration to show up as an installable option — or anything else to indicate HA is recognizing it.
I know the add-on and the integration are distinct, and I’m trying to understand if there’s some persistent state that’s blocking detection, or if I’ve missed a known workaround.
Any help appreciated — and yes, settings and WebSocket details have been triple-checked.
Does this appear on the Settings → Devices & Services page? This is the integration that you need.
There is no Integration called “Z-Wave JS”, just this “Z-Wave” one.
After several attempts I finally got it to work. The only thing I can think of is that persistance paid off. I did finally use the Z-Wave integration, not Z-Wave JS. The only other thing I can say the the terminology needs to be made clear and consistent. There has to be a clear change log available.There are way too many double names and deprecations out there.