{"id":16387712,"url":"https://github.com/shnhrrsn/homebridge-openzwave","last_synced_at":"2025-03-21T02:31:30.973Z","repository":{"id":47916078,"uuid":"233168935","full_name":"shnhrrsn/homebridge-openzwave","owner":"shnhrrsn","description":"OpenZWave platform for Homebridge.","archived":false,"fork":false,"pushed_at":"2023-01-05T05:11:51.000Z","size":962,"stargazers_count":20,"open_issues_count":25,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-20T16:15:53.247Z","etag":null,"topics":["homebridge","homebridge-platform","homebridge-plugin","iot","openzwave","zwave"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shnhrrsn.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-11T03:15:00.000Z","updated_at":"2025-03-16T13:40:07.000Z","dependencies_parsed_at":"2023-02-03T12:00:46.531Z","dependency_job_id":null,"html_url":"https://github.com/shnhrrsn/homebridge-openzwave","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shnhrrsn%2Fhomebridge-openzwave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shnhrrsn%2Fhomebridge-openzwave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shnhrrsn%2Fhomebridge-openzwave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shnhrrsn%2Fhomebridge-openzwave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shnhrrsn","download_url":"https://codeload.github.com/shnhrrsn/homebridge-openzwave/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244647075,"owners_count":20487009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["homebridge","homebridge-platform","homebridge-plugin","iot","openzwave","zwave"],"created_at":"2024-10-11T04:27:18.029Z","updated_at":"2025-03-21T02:31:30.615Z","avatar_url":"https://github.com/shnhrrsn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# homebridge-openzwave\n\n[![Latest Version](https://img.shields.io/npm/v/homebridge-openzwave.svg)](https://www.npmjs.com/package/homebridge-openzwave)\n[![Total Downloads](https://img.shields.io/npm/dt/homebridge-openzwave.svg)](https://www.npmjs.com/package/homebridge-openzwave)\n[![Build Status](https://cloud.drone.io/api/badges/shnhrrsn/homebridge-openzwave/status.svg)](https://cloud.drone.io/shnhrrsn/homebridge-openzwave)\n[![License](https://img.shields.io/npm/l/homebridge-openzwave.svg)](https://www.npmjs.com/package/homebridge-openzwave)\n\nOpenZWave 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.\n\nThis project was initially forked from [velocityzen/homebridge-platform-zwave](https://github.com/velocityzen/homebridge-platform-zwave) and has been completely rewritten in TypeScript.\n\n## Supported Z-Wave Command Classes\n\n- [SWITCH_BINARY](src/Accessories/Drivers/SwitchBinaryDriver.ts) (37)\n- [SWITCH_MULTILEVEL](src/Accessories/Drivers/SwitchMultiLevelDriver.ts) (38)\n- [SENSOR_BINARY](src/Accessories/Drivers/SensorBinaryDriver.ts) (48)\n- [SENSOR_MULTILEVEL](src/Accessories/Drivers/SensorMultiLevelDriver.ts) (49)\n- [BATTERY](src/Accessories/Drivers/BatteryDriver.ts) (128)\n\n## Requirements\n\n- Z-Wave Gateway\n  - [Aeotec Z-Stick Gen5](https://aeotec.com/z-wave-usb-stick)\n- [OpenZwave](https://github.com/OpenZWave/open-zwave)\n\nIn addition to OpenZwave, be sure to install the ozw dev package:\n\nFor Ubuntu/Debian:\n\n```bash\nsudo apt install libopenzwave1.5-dev\n```\n\nFor Alpine:\n\n```bash\nsudo apk --no-cache add openzwave-dev\n```\n\n## Installation\n\n1. [Homebridge](https://github.com/nfarina/homebridge)\n2. `npm i -g homebridge-openzwave`\n3. Add platform to your config file\n\n## Configuration\n\nIn order to use this plugin, you’ll need to add the following JSON object to your Homebridge config file:\n\n```json\n{\n  \"platform\": \"openzwave\",\n  \"name\": \"OpenZWave\",\n  \"zwave\": {\n    \"devicePath\": \"/dev/ttyACM0\"\n  }\n}\n```\n\n| Config Key         | Description                                                                                                                                             | Required |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |\n| `platform`         | Homebridge Platform name.\u003cbr\u003eThis value should always be openzwave.                                                                                     | Y        |\n| `name`             | The name of this platform within Homebridge.\u003cbr\u003eThis is mainly used for logs and can be any value you want.                                             | N        |\n| `zwave`            | This contains the settings that will be passed to OpenZWave.                                                                                            | Y        |\n| `zwave.devicePath` | The device path to your gateway.\u003cbr\u003eSee [Finding Your Device](#finding-your-device) for more information.]                                              | Y        |\n| `uuidPrefix`       | Override the default prefix used when generating UUIDs for each node.\u003cbr\u003e_NOTE: Most setups will not need to change this value._                        | N        |\n| `accessories`      | Customize how your Z-Wave accessories behave in HomeKit, or exclude them entirely.\u003cbr\u003eSee the [Accessories](#accessories) section for more information. | N        |\n\n### Finding Your Device\n\nTo 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.\n\nIf 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.\n\n### Accessories\n\nThe accessories config object allows you to customize how your devices appear and behave within HomeKit.\n\n```json\n{\n  \"platform\": \"openzwave\",\n  \"name\": \"Z-Wave Platform\",\n  \"zwave\": {\n    \"devicePath\": \"/dev/ttyACM0\"\n  },\n  \"accessories\": {\n    \"3\": {\n      \"name\": \"My Fan Control\",\n      \"classes\": {\n        \"ignored\": [128],\n        \"rewrite\": [{ \"from\": 38, \"to\": 999001, \"indexes\": { \"5\": 0 } }]\n      },\n      \"hints\": [\"fan\"]\n    }\n  }\n}\n```\n\n| Config Key                   | Description                                                                                                                                    |\n| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`                       | The default name this accessory should have in HomeKit.                                                                                        |\n| `commands`                   |                                                                                                                                                |\n| `commands.ignored`           | An array of [Z-Wave command classes](src/Zwave/CommandClass.ts) you’d prefer this plugin not represent in HomeKit.                             |\n| `commands.rewrite`           | An array of commands to rewrite to change their intended effect                                                                                |\n| `commands.rewrite[].from`    | The [Z-Wave command class](src/Zwave/CommandClass.ts) to replace                                                                               |\n| `commands.rewrite[].to`      | The [Z-Wave command class](src/Zwave/CommandClass.ts) to change to                                                                             |\n| `commands.rewrite[].indexes` | A key value list to map the index of the `from` command to the `to` command.                                                                   |\n| `hints`                      | An array of strings to better help the plugin understand what type of device this is.\u003cbr\u003eCurrently supported values are: `fan` and `presence`. |\n\n#### Excluding Accessories from HomeKit\n\nIf you have Z-Wave nodes you’d wish to exclude from HomeKit, you can hide them by setting the accessory to false:\n\n```json\n{\n  \"platform\": \"openzwave\",\n  \"name\": \"Z-Wave Platform\",\n  \"zwave\": {\n    \"devicePath\": \"/dev/ttyACM0\"\n  },\n  \"accessories\": {\n    \"3\": false\n  }\n}\n```\n\n## Device Handlers\n\n`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.\n\nFor more information on device handlers, see the [README](src/Devices/README.markdown).\n\n## Development\n\n### Environment\n\nAll development tooling dynamically configures OpenZWave through a `DEVICE_PATH` environment var that should be set to the location of your Z-Wave Gateway.\n\nA `.env` file is supported in the root of the project directory.\n\n### Tools\n\n`homebridge-openzwave` has some tooling to help making development easier:\n\n- `yarn testharness` will launch Homebridge through Babel/TypeScript pointed towards `src`\n- `yarn util ls` displays a list of devices currently in your Z-Wave network\n- `yarn util inspect :nodeid` query a specific node to display debug information including node info and command classes\n\n### Emulated Development\n\nYou can run the testharness with a docker flag to launch an Z-Wave emulator with test devices.\n\n```bash\nyarn testharness --docker\n```\n\n### Remote Development\n\nIf your Z-Wave Controller is plugged into a different machine, you can access it remotely via `socat`.\n\n\u003e NOTE: Be sure to shutdown Homebridge on the machine before you run `socat` as the gateway only supports a single connection to it.\n\nTo get started, run this on the machine that your Z-Wave Controller is plugged into:\n\n```bash\ndocker run --rm -ti  --privileged -p 32375:32375 -v /dev:/host/dev \\\nalpine/socat -d -d tcp-l:32375,reuseaddr,fork file:/host/dev/ttyACM0,raw,nonblock,echo=0\n```\n\n\u003e NOTE: Remember to update your `/dev` path to match the path from [Finding Your Device](#finding-your-device).\n\nNext, when launching the testharness on your local machine, pass through a `remote` flag:\n\n```bash\nyarn testharness --remote=$IP_OF_REMOTE_MACHINE:32375\n```\n\nThe testharness will handle launching socat on your local machine and configuring `DEVICE_PATH` for you.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshnhrrsn%2Fhomebridge-openzwave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshnhrrsn%2Fhomebridge-openzwave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshnhrrsn%2Fhomebridge-openzwave/lists"}