0Getting OpenZWave working with Home Assistant

I am slowly migrat­ing my smarthome setup to Home­As­sist­ant which, as with most open-source pro­jects, is pretty unfriendly to start with and takes some learn­ing to use. I have an Aeotec ZStick and an Aeotec Door­bell 6 which work via Z‑Wave and I wanted to cus­tom­ise the tones and reduce the volume a little. You’d think it would be easy right?

The first hurdle to over­come was to real­ise that Home Assist­ant has 2 ways to use Z‑Wave. One is built in, and one is built on the “Open­ZWave” sys­tem / soft­ware / dock­er image (or whatever it actu­ally is!). The built-in sys­tem does­n’t sup­port the latest Z‑Wave stand­ards and so could­n’t con­fig­ure my door­bell, but appar­ently the altern­at­ive Open­ZWave 1.6 sys­tem will be able to even­tu­ally, although it does­n’t seem to do so year. In order to avoid more issues in future the first thing to do is to switch from the built-in Z‑Wave sup­port to the Open­ZWave addon. Note that I am using the full “Home Assist­ant” (which used to be called Hass.io). It is basic­ally an all-in-one install with Has­sOS, and then both Home Assist­ant and “Super­visor” run­ning on top of that. Many people run this setup on a Rasp­berry Pi although I am run­ning on a 4W mini PC with a Pen­ti­um 4200 which is a lot like a low powered Intel NUC.

Before you start

Unpair your door­bell from your USB stick if it is already paired as we need to pair it in secure mode

Find your USB stick details

• Super­visor
• Sys­tem
• “Host Sys­tem” box
• “Hard­ware” button
• It should be some­thing like

  /dev/serial/by-id/usb-0658_0200-if00

Disable built-in zwave

• Con­fig­ur­a­tion
• Integ­ra­tions
• ZWave box
• Click con­fig­ure
• Click “Stop Network”

Install Mosquitto broker

• Super­visor
• Addons Store
• Search for mosquitto broker

Install MQTT

• Con­fig­ur­a­tion
• Integ­ra­tions
• Search for MQTT
• You should see the mosquitto broker lis­ted. Click configure

Install OpenZWave

• Super­visor
• Addon Store
• Search zwave

Generate a random key for security

• Go to Random.org and gen­er­ate a ran­dom hex code for a secur­ity key that you will need in the next step

Configure OpenZWave with your USB details

• Super­visor
• Dash­board
• Open­ZWave
• Con­fig­ur­a­tion
• Edit the “device” entry to match the USB path from above, and add the num­bers gen­er­ated in place of the ?? for the secur­ity key
• E.g.
  • device: /dev/seri­al/by-id/usb-0658_0200-if00
  • network_key: ‘0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??, 0x??’
• Click save
• Click on “Info” tab
• Click Start

Configure OpenZWave integration

• Con­fig­ur­a­tion
• Integ­ra­tions
• “Open­ZWave (beta)” box
• Click “Con­fig­ure”
• Click “Con­firm Setup”

Reboot!

I found at this point that I had to reboot for the sys­tem to start talk­ing to my USB Z‑Stick prop­erly, so I recom­mend reboot­ing at this point.

Setting up semi-friendly configuration interface

• Down­load and install the Open­ZWave GUI for win­dows (scroll to the bot­tom of the page and look for the link to the win­dows .msi)
• To use the GUi first go to Super­visor -> Open­Zwave -> Con­fig­ur­a­tion and set the host field to 1983 (it is dis­abled by default unless you enter a value)
• Then in Open­ZWave GUI just enter the IP or name of your home assist­ant. The port should already be cor­rect and no authen­tic­a­tion key is required
• Note that your USB device may show as not being Z‑Wave plus, but if any con­nec­ted devices are show­ing as Z‑Wave Plus you can safely ignore this, it is misleading.

Configuring the volume

Why on earth the default volume is set so loud it dis­torts is bey­ond me. Pre­sum­ably it is so that Aeotec can put some silly decibel num­ber on the box. How­ever, I don’t actu­ally want my door­bell to dam­age my ears, or wake my chil­dren at night either for that mat­ter, so the first thing I really needed to do was turn it down. You’d think after all the hoops we’ve already had to jump through that might be (finally) easy, but guess again…

Shutdown home assistant

• Shut­down Home Assistant
• Remove the USB Z‑Wave stick
• Con­nect it to a win­dows PC

Get Silicon Labs PC software

• Go to the Sil­ic­on Labs web­site down­loads page
• Select to down­load the PC Con­trol­ler Software
• Click on the “Cre­ate an Account” link and register
• Once you have veri­fied your account and logged in, go back to the down­loads page
• Down­load the Z‑Wave SDK First
• Then down­load the PC Con­trol­ler software
• Run the ZWaveControllerSetup.msi
• Extract the 2 files in the ZW050x_USB_VCP_PC_Driver folder, then right-click on the extrac­ted INF file and select “install” to install the drivers
• Plug your Z‑Wave dongle into your win­dows PC
• Run the Z‑Wave PC Con­trol­ler software
• Click on the gear wheel to select your USB Stick — mine appeared as “UZB” on COM4 and click “Detect”, then click “OK”
• Click on “Net­work Management”
• Click “add” and then press the pair­ing but­ton on the doorbell
• You will need the first 5 digits of the DSK code which are prin­ted on the back of the door­bell — the device will then pair in S2 mode
• The device should then appear as a “Sound Switch” in the under “slaves” in the box near the top left.
• Select the device and then click “Node Info”
• A list of sub­devices should appear — approx­im­ately 8 of them. Each of these rep­res­ents a dif­fer­ent alert
• Select the appro­pri­ate sub-device
• In the box below double click on “79 — SOUND_SWITCH”
• In the sec­tion to the right, in the drop­down box, select “0×05 — SOUND_SWITCH_CONFIGURATION_SET”
• Set the volume hex as you like (effect­ively in per­cent­age). I found 60 was about the same as my old door­bell — a clas­sic old elec­tric bell
• Click on the Send but­ton at the bottom
• Repeat the last 5 steps for each of the dif­fer­ent alerts you wish to change — I did it for all of them

Restore Home Assistant

• Close the PC Con­trol­ler Software
• Unplug the Z‑Stick and recon­nect it to your Home Assist­ant system
• Boot home assist­ant back up
• The pair­ing with the door­bell, and your new volume set­tings, should be remembered by the Z‑Stick

Credits for this go to several different people from whom I managed to pull the information together in entirety

• tom_l
• firstof9
• john­flor­in
• pjjameso
• sim­plex­tech
• Hen­cor