Major Hayden's Blog 🤠

Running Home Assistant in a Docker container with a Z-Wave USB stick

The Home Assistant project provides a great open source way to get started with home automtion that can be entirely self-contained within your home. It already has plenty of integrations with external services, but it can also monitor Z-Wave devices at your home or office.

Here are my devices:

Install the Z-Wave stick

Start by plugging the Z-Stick into your Linux server. Run lsusb and it should appear in the list:

# lsusb | grep Z-Stick
Bus 003 Device 006: ID 0658:0200 Sigma Designs, Inc. Aeotec Z-Stick Gen5 (ZW090) - UZB

The system journal should also tell you which TTY is assigned to the USB stick (run journalctl --boot and search for ACM):

kernel: usb 3-3.2: USB disconnect, device number 4
kernel: usb 3-1: new full-speed USB device number 6 using xhci_hcd
kernel: usb 3-1: New USB device found, idVendor=0658, idProduct=0200, bcdDevice= 0.00
kernel: usb 3-1: New USB device strings: Mfr=0, Product=0, SerialNumber=0
kernel: cdc_acm 3-1:1.0: ttyACM0: USB ACM device
kernel: usbcore: registered new interface driver cdc_acm
kernel: cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters

In my case, my device is /dev/ttyACM0. If you have other serial devices attached to your system, your Z-Stick may show up as ttyACM1 or ttyACM2.

Using Z-Wave in the Docker container

If you use docker-compose, simply add a devices section to your existing YAML file:

version: '2'
      - "8123:8123/tcp"
    network_mode: "host"
      - /dev/ttyACM0
      - /etc/localtime:/etc/localtime:ro
      - /mnt/raid/hass/:/config:Z
    image: homeassistant/home-assistant
    restart: always

You can add the device to manual docker run commands by adding --device /dev/ttyACM0 to your existing command line.


For this step, always refer to the instructions that came with your Z-Wave device since some require different pairing steps. In my case, I installed the battery, pressed the button inside the sensor, and paired the device:

Understanding how the sensor works

Now that the sensor has been added, we need to understand how it works. One of the entities the sensor provides is an alarm_level. It has two possible values:

If the sensor changes from 0 to 255, then someone opened the garage door. Closing the door would result in the sensor changing from 255 to 0.

Adding automation

Let’s add automation to let us know when the door is open:

Now that we can detect the garage door being open, we need a notification action. I love PushBullet and I have an action set up for PushBullet notifications already. Here’s how to use an action:

Here’s an example of my service data:

  "message": "Someone opened the garage door at home.",
  "title": "Garage door opened"

Press the orange and white save icon at the bottom right and you are ready to go! You can tilt the sensor in your hand to test it or attach it to your garage door and test it there.

If you want to know when the garage door is closed, follow the same steps above, but use 255 for From and 0 for To.

#docker #homeassistant #fedora #security