PSA: Zwavejs2mqtt has been renamed to Z-Wave JS UI

Configuration Z-Wave
1

To avoid confusion, zjs2mqtt has been officially renamed. MQTT support itself isn’t going anywhere, but we heard from many users that they found the old name confusing. This will eventually be a breaking change in that you must update your docker compose files to pull the new image. For now, the old one will continue to work (with a warning).

Edit: The addon has also been renamed, so no need to message frenck about it.

6 Likes
2

I assume the new images are available right now?

How long before there will be a forced transition?

At what point are the two images going to be equivalent?

i.e. if I run the latest tag of the zwavejs-ui image right now which equivalent version tag of zwavejs2mqtt will that be?

to transition from zwavejs2mqtt we would only need to change the repo name and all other settings remain the same in the docker run command between the two?

You realize tho that every single time there is a name change there will inevitably be months upon months of forum posts like “hey I saw a video/blog/forum post that I need to run zwavejs2mqtt but I can’t find it”.

And months upon months (years…) of people continuing to use the old name as if it’s interchangeable (which I guess it will be for a while…) just like we still have people using “Hassio” or asking why they don’t have a “Supervisor” link in the sidebar because they saw it in a blog post.

I think it’s ultimately going to cause way more confusion than it’s trying to solve.

2 Likes
3

The new images are available and they are equivalent already. I’m not sure how long we’ll keep building both.

A few environment variables were renamed, but for most users you just need to change the name of the image and recreate the container. The release notes document all changes.

Your opinion on the name change is noted. This was not a rash decision. It followed months of thought, planning, and coordination. Sometimes there are growing pains. That project is now used in a way that was never originally foreseen. It predates HA using zwavejs at all. Now, few users use the mqtt aspects of the application. And we hear continually from people who are confused about which addon to use. Or they set it up with both the zwavejs integration and the mqtt integration and then are confused why they see two sets of devices.

4

Hi,
I’ve been using yarn to build and install it. Any changes for this?

6

There shouldn’t be, other than pulling the new repo.

7

I do have to agree with @finity. I find this very confusing. The name is zwave js UI but, in HA there is an GUI… so users using only the build in version of zwavejs (and not zwavejs2mqtt) might be confused as to which one to use now…

With zwavejs2mqtt it’s inline with zigbee2mqtt and everyone should easily find out what each one does. Now it’s not so clear anymore.

8

I’m scratching my head. On one Home Assistant system I manage, the ZWaveJS2MQTT add-on shows an update to 1.0.0, which should be the new version, right?

But, on another system, I’m not seeing any updates available for the ZWaveJS2MQTT add-on, even after forcing a check for updates and a reboot. I don’t see any errors in the Supervisor log, so I’m confused. Is there some manual update necessary?

1 Like
9

It is no longer called the zwavejs2mqtt addon. Do you see the Z-Wavw JS UI addon?

10

I do not. It’s still listed in the add-on store screen as “ZWaveJS2MQTT.”

11

The name change was introduced in v1.0.0 of the add-on. I’m assuming you need to update first to that version to see the name change reflected in your environment.

As for your other system, confirm the community add-on store is installed. https://addons.community/#installation

12

Which is kind of the point. Zigbee2MQTT ONLY uses MQTT. ZWaveJS2MQTT can use MQTT, but the preferred method of integrating it - is using the websocket. As the people behind the project have already said, the MQTT part of it is largely unused these days. And the fact that you didn’t need an MQTT broker to use it - confused a lot of newcomers.

2 Likes
13

Right, I got that. The community add on store appears to be installed. I tried to add it again (just to see), and got an error that it’s already installed.

14

Wouldn’t worry - it’s still called ZWaveJS2MQTT on my end in the add-on store.
Maybe just give it a few days.

15

On my test HAOS instance, I went to the add-on store, clicked ... in the upper right corner, then “Check for updates”. After a few seconds it showed ZWaveJS2MQTT had an update.

image
image1302×688 46.8 KB

I went to ZWaveJS2MQTT, and clicked the update button. After a few minutes, it refreshed entirely on its own (I didn’t touch it) and now shows Z-Wave JS UI.

image
image1332×895 65 KB

So I don’t have an answer for why you are having a different experience, but I can confirm that it is possible to upgrade and see the new name.

16

Cross-referencing the GitHub issue you opened for this: ZWaveJS2MQTT Add-on not updated to ZWave JS UI · Issue #3894 · home-assistant/supervisor · GitHub

I’m experiencing the same behavior you describe, including that:

/mnt/data/supervisor/addons/git/a0d7b954/ has directories for both zwavejs2mqtt and zwave-js-ui

… yet ZWaveJS2MQTT still shows as version 0.47 with no update available, and there is no separate addon listed for Z-Wave JS UI either. The issue remains the same even if I uninstall the ZWaveJS2MQTT addon.

17

Is there a migration guide on this? I have 82 ZWave devices and I really don’t want to spend a week re-joining them all to my mesh.

I found this but it doesn’t really lay out the process, and mostly notes that I need to manually modify a bunch of things that I don’t understand, and I REALLY don’t want to break my setup. This guide has made me less certain of the outcome, not more.

Just a general note - if you are going to take an existing project with a huge number of users, then break it because you don’t like the name, maybe spend some time making sure the existing userbase can understand how to deal with the breaking changes being imposed. While this change might be nice for new users, it’s a pretty substantial monkey wrench thrown into the works for existing users.

1 Like
18

Maybe explain how you have installed the software and how you are using it (mqtt, yes or no?). It was a literal one line change for me.

The migration guide you have listed is for migrating from zwave2mqtt, the old OZW implementation. It has nothing to do with this project name change.

1 Like
19

I’m not sure what you’re referring to. The only change that has to be made is the name of the image you’re pulling in docker, or the addon you’re installing in HA. There is no migration necessary.

20

Sure! I have an RPi running docker with the following docker-compose.yaml file:

version: '3.7'
services:
  zwavejs2mqtt:
    container_name: zwavejs2mqtt
    image: zwavejs/zwavejs2mqtt:latest
    restart: always
    tty: true
    stop_signal: SIGINT
    environment:
      - SESSION_SECRET=blahblahblah
      - ZWAVEJS_EXTERNAL_CONFIG=/usr/src/app/store/.config-db
      # Uncomment if you want logs time and dates to match your timezone instead of UTC
      # Available at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - TZ=America/New_York
    networks:
      - zwave
    devices:
      # Do not use /dev/ttyUSBX serial devices, as those mappings can change over time.
      # Instead, use the /dev/serial/by-id/X serial device for your Z-Wave stick.
      - '/dev/serial/by-id/usb-Silicon_Labs_HubZ_Smart_Home_Controller_C0F00B56-if00-port0:/dev/zwave'
    volumes:
      - zwave-config:/usr/src/app/store
    ports:
      - '8091:8091' # port for web interface
      - '3000:3000' # port for Z-Wave JS websocket server
networks:
  zwave:
volumes:
  zwave-config:
    name: zwave-config

In Home Assistant, I have the “Z-Wave JS” integration installed with my 82 devices showing, communicating via websockets. I’m using the Mosquitto broker add-on running on my HA install.

The migration guide offers the following:

  • settings.json are almost the same. You can easily export them from Z2M and import them in Z-Wave JS UI by using the Export and Import buttons in Settings tab. After importing them you only will have to edit some Z-Wave settings and all Gateway Values entries as now the value ids have changed

I don’t understand the impact of what is being said here. What am I supposed to be doing here to deal with the changes in the value IDs?

  • scenes.json need to be rewritten for the same reason as valueIds have changed. We suggest to manually recreate them using the UI and trash the old one

In my case, I have no scenes.json so nothing for me to do here I don’t think. If I did, I would have no idea what to do apart from “blow everything away and do it all over again” which isn’t a great answer but not my problem I guess.

  • You cannot use the old OZW cache file but don’t worry it will be automatically generated and the nodes names/locations will be restored from nodes.json file

I don’t think this applies to me.

  • nodes.json can be imported but you will have to manually edit it and delete all nodes hassDevices as them will not work in the new implementation (alternatively instead of deleting you can manually convert them, see next steps)

Not sure what this is trying to tell me. My nodes.json does not contain the string hassDevices

  • Values ids unique strings have changed, in Z2M valueIds were identified by <nodeId>/<commandClass>/<endpoint>/<index> now they are <nodeId>/<commandClass>/<endpoint>/<property>/<propertyKey?> where property and propertyKey (can be undefined) can be both numbers or strings based on the value. So essentially if you are using Home Assistant or MQTT functions all topics will change, here you can see how we have translated some valueids of devices.js from the old format to the new one.

I think this might be talking about MQTT namespace and topics? It’s not clear to me, but maybe this doesn’t concern me as I’m not doing anything directly by interacting w/ the MQTT traffic.

  • List values are no longer handled as strings but as numbers by default. For example to change a Thermostat Mode in Z2M you used to send Heat or Off now you will need to send 1 (Heat) or 0 (Off). This will make it lot easier to handle list values
  • All bitmask values are now split in separated values and are booleans. The same for RGB colors, now all colors will be handled separately, there will be a valueId to control Red (0-255), another for Green (0-255) and so on… There is an open issue on Z-Wave JS to also create a valueId with the hex color string. Also now some values are split in targetValue and currentValue, the first one is used to send commands the second one to see the actual state. This could seems tricky at first sight but there are some reasons behind this.

Are these more MQTT concerns? I have no idea.

21

I’m referring to this guide in the project documentation.

edit: I’m wondering if that’s for the not-js version? Maybe that guide doesn’t apply to me? I can certainly agree with the OPs point that the naming here is confusing as heck :smiley: