Get OpenZWave Beta working

Tags: #<Tag:0x00007f7398c7cb40> #<Tag:0x00007f73993e3e10>

While this is a beta integration, please consider the following from the 0.110 release blog

It is still early days for this integration, though; not all platforms and devices are supported yet and the setup process has prerequisites that raise the accessibility bar. See our documentation for the current requirements and instructions.

If you want to give it a shot, you should be comfortable with setting up custom add-ons and MQTT. There is no migration from the current Z-Wave integration yet, this is still to come.

The plan is to add more platforms in the future, making it super simple to set up the integration. Stay tuned.

There is currently no plan to deprecate the existing Z-Wave integration. But the hope is that the new integration, in the future, will offer a simpler, more stable and more feature-rich experience than the current Z-Wave integration.

In total, there are three parts to using the new OpenZWave (beta)

1 - ozwdaemon – This is either an add-on or it could be in a docker container ( Even a “bare-metal” install ). This just needs to be running somewhere on your network.

2 - A mqtt broker ( I use mosquitto ) running somewhere – This could be an add-on, a docker container, a “bare-metal” install or even in the cloud.

3 - Open ZWave (beta) - This is the new Z-Wave integration for Home Assistant – Install this from the integrations page in Home Assistant – Note: This is the same component as the HACS pre-release . The name has been changed as it moved from pre-release to beta. This name change was to avoid confusion with the unrelated zwave2mqtt project.


Here’s what I did to get OpenZWave functionality working on Home Assistant Supervised (should also work for full Home Assistant):

  1. Install Mosquitto Broker from Supervisor-Addon Store-Official Addons (no config needed)
  2. Install MQTT integration from Configuration-Integrations (no config needed)
  3. Install the Openzwave addon from Supervisor-Addon Store-Official Addons

Its configuration looked like this in my case, I chose to go with no network security key, as I have no locks and had issues getting it to work with the key:

device: /dev/serial/by-id/usb-0658_0200-if00
network_key: ''

To find out your own device ID, in your host terminal/SSH type “ls /dev/serial/by-id/”

  1. Installed the OpenZWave (beta) integration from Configuration-Integrations (no config needed)

At this point, if you already had a stick with devices saved to it, they should start being created in HA and visible in Configuration-Devices.

If you started with a new stick, there’s this step as well:

  1. Go to Developer Tools-Services, select ozw.add_node and hit Call Service. This will take your controller into inclusion mode and enable pairing of new devices. So, you can hit Call Service and press whatever pairing button is needed on your device. There is no feedback at all in the UI, except for the hopeful appearance of your new device in Configuration-Devices.

Optionally, you can also download OZWAdmin, which is a GUI made by the OpenZWave developer to handle certain aspects of the node configuration and monitoring. The current build that works with the HA addon is 96, available here: - in order to use this, go to Supervisor-OpenZwave-Configuration and put 1983 in the Host field. Afterwards, download OZWAdmin on any PC with a GUI and connect to your instance via your IP & port 1983. I’d like to point out that this is an excellent tool for checking and/or modifying all the node parameters, with clear explanations of what each parameter does.

Thanks to everyone that helped get me up and running!


No add-ons, no problem

Here’s a few alternative ways for running ozwdaemon

I’m running Home Assistant Core ( virtualenv ) from a jail on my FreeNAS. Unfortunately, there is no easy solution for running ozwdaemon on FreeNAS so I decided to use a RPI 3B+ running Raspbian Buster Lite with Docker to provide the ozwdaemon.

:warning: Attention FreeNAS ( FreeBSD ) Users – unofficial work in progress

Using a RPI with Docker to run ozwdaemon ( minimal setup )

There are already, many guides and videos around the internet to provide details about installing and using both Raspbian and Docker. Based on such guides, I have put together this outline of the minimal steps I used to setup my RPI for running ozwdaemon.


I used Raspberry Pi Imager to flash raspbian-lite on the sdcard

Enable ssh

# cd /mnt/sdcard/boot
touch ssh

Configure WiFi - optional method 1

# cd /mnt/sdcard/boot
nano wpa_supplicant.conf
  • In this file, add something like the following
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev 
    psk="Your Network's Passphrase"

RPI First Boot

Connect to the RPI using ssh

  • default password is raspberry
ssh [email protected]

Configure the RPI

sudo raspi-config

8 - Update - optional, this only updates raspi-config

1 - Change password for user pi

2 - Network options

  • N1 - change the hostname
  • N2 - setup wifi - optional method 2

4 - Localisation options

  • I1 - Set Locale
  • I2 - Set Time Zone
  • I4 - WiFi Country - optional, if not using wifi

Install system updates and reboot

sudo apt update && sudo apt dist-upgrade && sudo apt autoremove
sudo reboot

RPI Second Boot

Connect to the RPI using ssh - Did you change the hostname?

ssh [email protected]

Install Docker

wget -O
sh ./

Add user to the docker group

sudo usermod -aG docker pi

You need to log out, then log back in to apply these user permissions

Run a Docker Command

  • Simple test to be sure your user can run docker
  • You’ll see an error if docker needs to be run as root
docker version

That’s it! Your RPI should now be ready to starting running docker containers

docker run -it --security-opt seccomp=unconfined --device=/dev/ttyACM0 -v /tmp/ozw/config:/opt/ozw -e MQTT_SERVER="" -e USB_PATH=/dev/ttyACM0 openzwave/ozwdaemon:latest

Using Docker Compose

If you’re comfortable using the command line, it may be preferred to manage your docker containers using Docker Compose.

Install Docker Compose

sudo apt install docker-compose

Create a compose file

nano docker-compose.yml
  • This is an example for ozwdaemon
  • In this file, add something like the following
version: '3'

  ## qt-openzwave (ozwdaemon)
    container_name: "ozwdaemon"
    image: openzwave/ozwdaemon:latest
      - 1983:1983
    restart: unless-stopped
      - seccomp:unconfined
      - ozwd:/opt/ozw/config
      - "/dev/ttyACM0:/dev/ttyACM0"
      MQTT_SERVER: ""
      #MQTT_USERNAME: "ozw"
      #MQTT_PASSWORD: "SuPeR!sEcret"
      USB_PATH: "/dev/ttyACM0"
      OZW_NETWORK_KEY: "0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x11,0x12,0x13,0x14,0x15,0x16"
      #QT_LOGGING_RULES: "*.debug=false;ozw.library.debug=true"


Starting the ozwdaemon service

docker-compose up -d

If you started Compose with docker-compose up -d, you can stop your services with:

docker-compose stop

Using Portainer

For now, I’ve decided I’m going to try Portainer to manage my the container(s) on the RPI. If nothing else, I like having the convenience of a web-ui, that can be added to Home Assistant Core, by using an iframe panel.

Create a volume for Portainer data

docker volume create portainer

Run Portainer

docker run -d -p 9000:9000 --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v portainer:/data portainer/portainer

Now from a web browser, you should be able to reach portainer at http://docker_host_address:9000

Create a stack file

Portainer stacks are deployed using the equivalent of docker-compose. Only Compose file version 2 is supported at the moment.

  • This is an example for ozwdaemon
  • In this file, add something like the following
version: '2'

  ## qt-openzwave (ozwdaemon)
    container_name: "ozwdaemon"
    image: openzwave/ozwdaemon:latest
      - 1983:1983
    restart: unless-stopped
      - seccomp:unconfined
      - ozwd:/opt/ozw/config
      - "/dev/ttyACM0:/dev/ttyACM0"
      MQTT_SERVER: ""
      #MQTT_USERNAME: "ozw"
      #MQTT_PASSWORD: "SuPeR!sEcret"
      USB_PATH: "/dev/ttyACM0"
      OZW_NETWORK_KEY: "0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x11,0x12,0x13,0x14,0x15,0x16"
      #QT_LOGGING_RULES: "*.debug=false;ozw.library.debug=true"


Adding to what @troy provided just above, here are steps to get MQTT Broker, OZW daemon, and Home Assistant up and going in docker containers on a Pi running Raspbian by using docker-compose for each of them.

Installing Mosquitto Broker, QT-OZWDaemon, and Home Assistant Core in Docker on a Raspberry Pi Running Raspian

I did this on a Raspberry Pi3B+ running Raspbian Lite (Buster), connected over ssh via network cable to my network. This uses the eclipse-mosquitto Broker from, the OZW daemon being developed for HA, and the current release of Homeassistant Core (0.110.3 as of this writing).

I haven’t needed or tried creating an OZW_NETWORK_KEY for openzwave. It’s commented out in the script below.

Lastly, don’t enter the “$” for any commands below, just the command itself.

Precursor Steps

  • Install Raspbian, update and upgrade it
  • Get ssh working or use a mouse, keyboard, and monitor connected directly to the Raspberry Pi
  • Log in as pi user
  • Install docker after first installing its precursors
  • Install docker-compose

Take note of your Pi’s IP address for use below from your router as <Your Pi IP Address>. Or, you can run:

$ ifconfig
to get the IP address if you don’t know it from your router.

The IP address will be one of the inet values, probably starting with 192.168.x.x, from the eth0 entry if you’re hardwired to your network.

Create directories:

$ sudo mkdir –m 777 /srv/mosquito
$ sudo mkdir –m 777 /srv/mosquito/data
$ sudo mkdir –m 777 /srv/mosquito/log
$ sudo mkdir -m 777 /srv/ozw
$ sudo mkdir –m 777 /srv/homeassistant

Create the mosquitto.conf File for the Mosquitto Broker using the text editor of your choice, perhaps nano.

$ cd ~/
$ nano mosquitto.conf

Add the following to the new file to allow the MQTT Broker to retain its state and information between restarts and to write log data. Also, this guide assumes anonymous credentials for MQTT. Do something else if that’s not for you, like adding and encrypting a MQTT password file, or using the HA MQTT add-in on HA Supervised.

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
allow_anonymous true

Save the file and exit the editor

Create docker-compose.yml in the “pi” User’s Home Directory to Manage the Docker Containers
The /dev/ttyxxxx devices onto which the zwave controller lands when plugged into the USB port are generally these:

/dev/ttyUSB0  for HUSBZ-1 zwave
/dev/ttyUSB1 for HUSBZ-1 zigbee
/dev/ttyACM0 for Aeotec Gen 5, or sometimes
/dev/ttyAMA0 for Aeotec Gen 5

Note: Replace the “/dev/tty****” entries in the script below to match your configuration. (Insert your zwave controller into one of the Pi’s USB port and look in /dev/ for the devices).

$ ls /dev/tty*

The processes further down this guide will fail if you reference /dev/ttyxxx devices that don’t exist on the Pi).

Also, replace TZ=America/Los_Angeles with your time zone

And make sure you use the <Your Pi IP Address> where indicated.

$ cd ~/
$ nano docker-compose.yml

Add the following to the new file being very careful to maintain the indentation as shown:

version: '3'
# ~~~~~~~~~~~~~~~~~
# Start of Mosquitto
    container_name: "mosquitto"
    image: eclipse-mosquitto:latest
      - /srv/mosquitto/data:/mosquitto/data
      - /srv/mosquitto/log:/mosquitto/log
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
    network_mode: "host"
      - "1883:1883"
      - "9001:9001"
    restart: unless-stopped
# End of Mosquitto
# ~~~~~~~~~~~~~~~~
# Start of openzwave daemon
    image: openzwave/ozwdaemon:latest
    container_name: "qt-openzwave"
      - seccomp:unconfined
      - /dev/ttyUSB0:/dev/ttyUSB0
      - /srv/ozw:/opt/ozw/config
      MQTT_SERVER: <Your Pi IP Address>
#      MQTT_USERNAME: ""
#      MQTT_PASSWORD: ""
      USB_PATH: /dev/ttyUSB0
      - 1983:1983
#      OZW_NETWORK_KEY: "0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00"
    restart: unless-stopped
      - mosquitto
# End of openzwave daemon
# ~~~~~~~~~~~~~~~
# Start of Home Assistant
    container_name: home-assistant
    image: homeassistant/home-assistant:stable
      - /srv/homeassistant:/config
# Any devices not found in /dev will cause the script to FAIL!
# Edit this list as necessary
      - /dev/ttyUSB0:/dev/ttyUSB0
      - /dev/ttyUSB1:/dev/ttyUSB1
      - /dev/ttyACM0:/dev/ttyACM0
      - TZ=America/Los_Angeles
    restart: always
    network_mode: host
      - mosquitto
      - qt-openzwave
    restart: unless-stopped
# End of Home Assistant
# ~~~~~~~~~~~~~~~~~
# End-of-File

Save the file and exit.

Create and Start the Docker Containers by Running docker-compose
This takes you to the pi users home directory, creates & loads the docker containers, and runs them as daemons.

$ cd ~/
$ sudo docker-compose pull
$ sudo docker-compose up –d

You should see messages for mosquitto, qt-openzwave, and home-assistant that report “done.”

Open the New Instance of homeassistant in a Browser on your Network
Enter: <your Pi IP address>:8123
It may take a few moments to come fully up before it will display.

Configure New User, etc., following the Prompts to get Logged into HA
Follow the prompts in HA.

Add MQTT and OZW Integrations to HA
Go to Configuration>Integrations
Add MQTT Integration
Enter <your Pi IP address>
(Leave user and password empty
or, instead of the integration, edit /srv/homeassistant/configuration.yaml and add:

  broker:  <your Pi IP address>
  port: 1883

Restart HA
Configuration> Server Controls> Restart

Go to Configuration>Integrations
Add OZW Integration
(It will likely show your controller as a found device)

That should DO IT!

View or Add Zwave Devices
Go to Overview in HA and you should see or start seeing zwave devices that are on your zwave controller.

If your controller is new, go Developer>Services, select and run the ozw.add_node service, and start adding your zwave devices by putting each device in turn into its include mode.

1 Like

Renaming devices
Until a proper migration or renaming tool is developed we will need to rename the freshly discovered devices and entities into something more useful. Devices and entities get their names from OpenZwave and those are the names provided by the manufacturer and they don’t know whether your device is in the kitchen or living room.

Steps I took to migrate

  1. Before migration, copy paste the list of entities to Excel. You can do this from the States menu under developer tools. Filter Attributes with “node_id:”. This will give you all your old Zwave entities.
  2. After migration, go to a new OZW device (screenshot: click on 2A), inside the entity click the top right button (2B) and find the node id in the bottom right corner (2C).
  3. Back to the device page. Click the wheel in top right corner (3A) and rename the device (3B). It will ask you to rename all entities as well.

    step 2B
    step 2C
    step 3B

Seems like the hass-cli tool might be just the thing to use in a shell script to gather this information. I’ve used it in the past to rename a bunch of zwave entity names that got automatically created with ugly names.