ZWave with HomeAssistant

A couple of weeks ago I talked about different protocols for smart devices, and today I’m going to go through setting up ZWave with HomeAssistant.

I bought the Aeon Z-Stick Gen 5 USB controller, which is on the supported devices list. I recall some difficulty in setting it all up, but then I’m being awkward and running on CentOS. If you use the docker image or Raspberry Pi all in one installer for HA it’ll probably work out of the box.

The Z-Stick will appear as something like /dev/ttyACM0, but it’s definitely worth following the instructions to give this a friendly name that is persistent across reboots as that name can change. There will be an existing symlink to it under /dev/serial/by-id/ but it’s much easier to remember /dev/zwave:

$ ls -l /dev/serial/by-id/usb-0658_0200-if00 
lrwxrwxrwx 1 root root 13 Feb 19 17:40 
/dev/serial/by-id/usb-0658_0200-if00 -> ../../ttyACM0

$ cat /etc/udev/rules.d/99-usb-serial.rules 
SUBSYSTEM=="tty", ATTRS{idVendor}=="0658", ATTRS{idProduct}=="0200", SYMLINK+="zwave"

$ ls -l /dev/zwave 
lrwxrwxrwx 1 root root 7 Feb 19 17:40 
/dev/zwave -> ttyACM0

Once that’s set up, incorporating it into HA is as easy as adding the following to your configuration.yaml:

zwave:
  usb_path: /dev/zwave

The next step is to pair a device. I needed a new door sensor and picked up a Hauppage 4-in-1 sensor from their mySmartHome range. It’s obviously designed to work with the Hauppage controller, but I took a chance that it’d work with any ZWave controller. I also noticed that it looks identical to the Philio 4-in-1 sensor so I figured it was just a rebranding. The Hauppage version was a bit cheaper.

If you only need a door sensor you can get even cheaper sensors, but I liked the option to see the temperature as well.

Pairing devices involves pressing the button on the Z-Stick, calling the add_node service within HA, and then following the device specific instructions.

In the case of the Hauppage sensor that meant flicking the tamper switch three times in quick succession – twice.

It’s not clear from the instructions but you have to do it twice – first to exclude the device and then to include it, although you don’t have to run remove_node during the exclude step. I assume it just clears the device itself and then it’s available to include.

Once the device is paired, it should show up in the list of entities when you browse the device states:

As you can see, it is indeed the Philio sensor. You can also see each of the sensor types and see that the node_id is 6. This corresponds to another entity, and that’s where you can find the battery level attribute:

At this point you could rename the node itself with the ZWave rename_node command so that it’s got a more useful name, but I chose not to. I’ve decided to leave the physical device names untouched and change the friendly_name within HA. I don’t want to rename the node as, say, “front_door” and then have to change it again if I decide to move the sensor to another door. Much easier to leave the hardware device name alone and use HA’s configuration options to make it user friendly.

You may also have noticed that the sensor.philio_technology_corporation_pst02a_4_in_1_multisensor_access_control_6_9 entity has a value of 23. The access_control entity is the open/closed sensor, so why 23?

The answer lies on page 73 of the ZWave command specification (N-Z):

The value 0x16 (22 in decimal) is used when a window or door is open, and 0x17 means it’s closed.

Not something you’re going to want to remember, is it?

The solution is to use a template sensor to map the values to the words “open” and “closed” under your sensors section – which in my case is a separate file called sensors.yaml

In configuration.yaml I have:

sensor: !include includes/sensor.yaml

and in includes/sensor.yaml:

- platform: template
  sensors:
    front_door_access:
      value_template: '{% if is_state("sensor.philio_technology_corporation_pst02a_4_in_1_multisensor_access_control_6_9", "22") %}open{% else %}closed{%endif %}'
      friendly_name: "Front Door" 

Putting this into a group called “Door” completes the picture:

This is also why I didn’t bother to rename the physical device itself. The template sensor is the one I’ll use in automations, so instead of:

- alias: "Do something when door opens"
  trigger:
    platform: state
    entity_id: sensor.philio_technology_corporation_pst02a_4_in_1_multisensor_access_control_6_9
    to: "22"

I can write the much clearer:

- alias: "Do something when door opens"
  trigger:
    platform: state
    entity_id: sensor.front_door_access
    to: "open"

Finally I exposed the temperature as “Front Door” in a group. In customise.yaml or the customise section of configuration.yaml:

sensor.philio_technology_corporation_pst02a_4_in_1_multisensor_temperature_6_1:
  friendly_name: Front Door

And in group.yaml or the group section of configuration.yaml:

temperature:
  name: Temperature
  entities:
    - sensor.philio_technology_corporation_pst02a_4_in_1_multisensor_temperature_6_1

If you’ve been following this blog closely (and you have, haven’t you?) you may recall the automation that I set up to turn on a light when the door opened after dark. That was using a sensor on my front door and I was using the SmartThings sensor via the bridge. So why change to a ZWave sensor?

The short answer is that my SmartThings sensors have been playing up. It’s a story that I’ll expand on another time, but for now suffice to say that I’m slowly moving across to ZWave and HA.

in Home Automation

Related Posts