Z-Wave: switch from JS to JS UI add-on: add some steps #40007
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull Request Overview
This PR refines the documentation for switching from the Z-Wave JS add-on to the Z-Wave JS UI add-on by clarifying steps, updating headings, and improving formatting.
- Cleaned up duplicate wording around switching between add-ons
- Updated the “How to switch” heading and detailed sub-steps with bold UI strings and icons
- Enhanced descriptions under “What’s the benefit” with consistent link and bold styling
Comments suppressed due to low confidence (2)
source/_integrations/zwave_js.markdown:986
- The nested bullet list under step 5 isn’t surrounded by blank lines, and indentation is inconsistent. Add a blank line before the sub-list and indent nested bullets by at least two spaces for proper Markdown rendering.
5. Add the Z-Wave integration again (even though it is still installed).
source/_integrations/zwave_js.markdown:970
- [nitpick] For consistency with other occurrences, wrap Z-Wave JS and Z-Wave JS UI in bold so UI strings are styled uniformly throughout the document.
You can switch between the official Z-Wave JS add-on and the Z-Wave JS UI add-on. However, you cannot run them both at the same time. Only one of them can be active at the same time.
|
|
||
| 2. Note your network security keys from the official add-on. | ||
| 2. Install and start the Z-Wave JS UI add-on. |
There was a problem hiding this comment.
You shouldn't start the new add-on until reconfiguration is done since that will cause a USB device access conflict.
I'd install the new add-on and configure it with the network keys. Note the URL of the add-on to connect to, as this will be used in the reconfigure flow. Then reconfigure the integration to use the new add-on URL. Then start the new add-on.
There was a problem hiding this comment.
Maybe add a note that the add-on will normally take a while to start up after start is pressed and the integration will retry the connection to the server in the add-on if the first attempt fails.
There was a problem hiding this comment.
Actually we may have a connection check in the flow already, so we need to start the add-on when coming to the form to enter the URL. That will ensure the connection succeeds before the flow is finished.
There was a problem hiding this comment.
I'm running Core 2025.7.2, Z-Wave JS 0.18, Z-Wave JS UI 4.7. I needed to start the JS UI add on in order to be able to access the configuration settings. It was not an issue for me that the add-on was started.
|
|
||
| 2. Note your network security keys from the official add-on. | ||
| 2. Install and start the **Z-Wave JS UI** add-on. |
There was a problem hiding this comment.
We can't start the add-on until we come to the URL form in the reconfigure flow.
There was a problem hiding this comment.
but then how do you change the configuration in the Z-Wave JS Web UI?
I had to start it in order to get here and enter the keys
There was a problem hiding this comment.
Ok, right. That add-on won't access the device immediately when the add-on is started the first time but after configuring the device and applying that in the Z-Wave JS UI GUI.
So it's ok to start the add-on, but we need to start the reconfigure flow, reaching the URL step, before applying the device settings and starting the driver.
Side note: With the complexity of these steps, we should consider having an explicit choice for reconfiguring from the official add-on to the Z-Wave JS UI add-on in the reconfigure flow, that walks the user through the needed steps.
There was a problem hiding this comment.
I don't understand what you mean by "but we need to start the reconfigure flow, reaching the URL step, before applying the device settings and starting the driver."
the order described here worked for me.
There was a problem hiding this comment.
Having two different processes accessing the same serial (USB) device isn't supported and may lead to issues and weird behavior. That's why we disabled the existing config entry before and why we should start the reconfigure flow before letting the driver run by Z-Wave JS UI access the device.
Starting the reconfigure flow and deselecting add-on to get to the manual URL form will stop the official add-on.
There was a problem hiding this comment.
I'm not trying to argue with you, I just don't quite understand what the order is. I reordered the steps now. Is it correct this way? Part of the reconfiguration steps are done twice, but I didn't see how else to do it. Maybe I am still missing something?
There was a problem hiding this comment.
You shouldn't reconfigure twice. That flow should still be open. The Z-Wave JS UI can be accessed in a separate tab.
If this is too complicated at the moment, we can keep the instruction to disable the config entry. Although we're moving away from that way of allowing reconfiguration via creating a new config entry which updates an existing config entry.
|
Thanks! |
Proposed change
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.