homebridge-openzwave

OpenZWave platform for Homebridge. The main goal of this project is to map Z-Wave protocol command classes to HomeKit Accessories, Services, and Characteristics. Theoretically, it should make it support any Open Z-Wave device.

This project was initially forked from velocityzen/homebridge-platform-zwave and has been completely rewritten in TypeScript.

Supported Z-Wave Command Classes

SWITCH_BINARY (37)
SWITCH_MULTILEVEL (38)
SENSOR_BINARY (48)
SENSOR_MULTILEVEL (49)
BATTERY (128)

Requirements

Z-Wave Gateway
- Aeotec Z-Stick Gen5
OpenZwave

In addition to OpenZwave, be sure to install the ozw dev package:

For Ubuntu/Debian:

sudo apt install libopenzwave1.5-dev

For Alpine:

sudo apk --no-cache add openzwave-dev

Installation

Homebridge
npm i -g homebridge-openzwave
Add platform to your config file

Configuration

In order to use this plugin, you’ll need to add the following JSON object to your Homebridge config file:

{
  "platform": "openzwave",
  "name": "OpenZWave",
  "zwave": {
    "devicePath": "/dev/ttyACM0"
  }
}

Config Key	Description	Required
`platform`	Homebridge Platform name. This value should always be openzwave.	Y
`name`	The name of this platform within Homebridge. This is mainly used for logs and can be any value you want.	N
`zwave`	This contains the settings that will be passed to OpenZWave.	Y
`zwave.devicePath`	The device path to your gateway. See Finding Your Device for more information.]	Y
`uuidPrefix`	Override the default prefix used when generating UUIDs for each node. NOTE: Most setups will not need to change this value.	N
`accessories`	Customize how your Z-Wave accessories behave in HomeKit, or exclude them entirely. See the Accessories section for more information.	N

Finding Your Device

To locate your Z-Wave controller, try running ls /dev/tty.* or ls /dev/cu.* in terminal. Depending on your OS, you may also be able to run ls -lah /dev/serial/by-id to find additional context for which device in your Z-Wave gateway.

If you’re unable to figure out the correct device, try unplugging it and running the commands above, after that, plug it back in and look for the additional device that wasn’t there before.

Accessories

The accessories config object allows you to customize how your devices appear and behave within HomeKit.

{
  "platform": "openzwave",
  "name": "Z-Wave Platform",
  "zwave": {
    "devicePath": "/dev/ttyACM0"
  },
  "accessories": {
    "3": {
      "name": "My Fan Control",
      "classes": {
        "ignored": [128],
        "rewrite": [{ "from": 38, "to": 999001, "indexes": { "5": 0 } }]
      },
      "hints": ["fan"]
    }
  }
}

Config Key	Description
`name`	The default name this accessory should have in HomeKit.
`commands`
`commands.ignored`	An array of Z-Wave command classes you’d prefer this plugin not represent in HomeKit.
`commands.rewrite`	An array of commands to rewrite to change their intended effect
`commands.rewrite[].from`	The Z-Wave command class to replace
`commands.rewrite[].to`	The Z-Wave command class to change to
`commands.rewrite[].indexes`	A key value list to map the index of the `from` command to the `to` command.
`hints`	An array of strings to better help the plugin understand what type of device this is. Currently supported values are: `fan` and `presence`.

Excluding Accessories from HomeKit

If you have Z-Wave nodes you’d wish to exclude from HomeKit, you can hide them by setting the accessory to false:

{
  "platform": "openzwave",
  "name": "Z-Wave Platform",
  "zwave": {
    "devicePath": "/dev/ttyACM0"
  },
  "accessories": {
    "3": false
  }
}

Device Handlers

homebridge-openzwave supports global/shared device handlers to override default Z-Wave behavior. This can be useful for devices that use generic commands for more specific purposes, such as a fan control that only implements SWITCH_MULTILEVEL.

For more information on device handlers, see the README.

Development

Environment

All development tooling dynamically configures OpenZWave through a DEVICE_PATH environment var that should be set to the location of your Z-Wave Gateway.

A .env file is supported in the root of the project directory.

Tools

homebridge-openzwave has some tooling to help making development easier:

yarn testharness will launch Homebridge through Babel/TypeScript pointed towards src
yarn util ls displays a list of devices currently in your Z-Wave network
yarn util inspect :nodeid query a specific node to display debug information including node info and command classes

Emulated Development

You can run the testharness with a docker flag to launch an Z-Wave emulator with test devices.

yarn testharness --docker

Remote Development

If your Z-Wave Controller is plugged into a different machine, you can access it remotely via socat.

NOTE: Be sure to shutdown Homebridge on the machine before you run socat as the gateway only supports a single connection to it.

To get started, run this on the machine that your Z-Wave Controller is plugged into:

docker run --rm -ti  --privileged -p 32375:32375 -v /dev:/host/dev \
alpine/socat -d -d tcp-l:32375,reuseaddr,fork file:/host/dev/ttyACM0,raw,nonblock,echo=0

NOTE: Remember to update your /dev path to match the path from Finding Your Device.

Next, when launching the testharness on your local machine, pass through a remote flag:

yarn testharness --remote=$IP_OF_REMOTE_MACHINE:32375

The testharness will handle launching socat on your local machine and configuring DEVICE_PATH for you.

homebridge-openzwaveOpenZWave platform for Homebridge.