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_MULTILEVEL (49)
- BATTERY (128)
Requirements
- Z-Wave Gateway
- 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:
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.
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 the only supported value is fan . |
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:
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 towardssrc
yarn util ls
displays a list of devices currently in your Z-Wave networkyarn 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.