Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shnhrrsn/homebridge-openzwave
OpenZWave platform for Homebridge.
https://github.com/shnhrrsn/homebridge-openzwave
homebridge homebridge-platform homebridge-plugin iot openzwave zwave
Last synced: 9 days ago
JSON representation
OpenZWave platform for Homebridge.
- Host: GitHub
- URL: https://github.com/shnhrrsn/homebridge-openzwave
- Owner: shnhrrsn
- License: mit
- Created: 2020-01-11T03:15:00.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T05:11:51.000Z (almost 2 years ago)
- Last Synced: 2024-10-12T04:27:16.283Z (25 days ago)
- Topics: homebridge, homebridge-platform, homebridge-plugin, iot, openzwave, zwave
- Language: TypeScript
- Homepage:
- Size: 939 KB
- Stars: 19
- Watchers: 5
- Forks: 4
- Open Issues: 25
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE
Awesome Lists containing this project
README
# homebridge-openzwave
[](https://www.npmjs.com/package/homebridge-openzwave)
[](https://www.npmjs.com/package/homebridge-openzwave)
[](https://cloud.drone.io/shnhrrsn/homebridge-openzwave)
[](https://www.npmjs.com/package/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](https://github.com/velocityzen/homebridge-platform-zwave) and has been completely rewritten in TypeScript.
## Supported Z-Wave Command Classes
- [SWITCH_BINARY](src/Accessories/Drivers/SwitchBinaryDriver.ts) (37)
- [SWITCH_MULTILEVEL](src/Accessories/Drivers/SwitchMultiLevelDriver.ts) (38)
- [SENSOR_BINARY](src/Accessories/Drivers/SensorBinaryDriver.ts) (48)
- [SENSOR_MULTILEVEL](src/Accessories/Drivers/SensorMultiLevelDriver.ts) (49)
- [BATTERY](src/Accessories/Drivers/BatteryDriver.ts) (128)
## Requirements
- Z-Wave Gateway
- [Aeotec Z-Stick Gen5](https://aeotec.com/z-wave-usb-stick)
- [OpenZwave](https://github.com/OpenZWave/open-zwave)
In addition to OpenZwave, be sure to install the ozw dev package:
For Ubuntu/Debian:
```bash
sudo apt install libopenzwave1.5-dev
```
For Alpine:
```bash
sudo apk --no-cache add openzwave-dev
```
## Installation
1. [Homebridge](https://github.com/nfarina/homebridge)
2. `npm i -g homebridge-openzwave`
3. 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:
```json
{
"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](#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](#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.
```json
{
"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](src/Zwave/CommandClass.ts) 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](src/Zwave/CommandClass.ts) to replace |
| `commands.rewrite[].to` | The [Z-Wave command class](src/Zwave/CommandClass.ts) 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:
```json
{
"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](src/Devices/README.markdown).
## 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.
```bash
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:
```bash
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](#finding-your-device).
Next, when launching the testharness on your local machine, pass through a `remote` flag:
```bash
yarn testharness --remote=$IP_OF_REMOTE_MACHINE:32375
```
The testharness will handle launching socat on your local machine and configuring `DEVICE_PATH` for you.