diff --git a/README.md b/README.md index 3b1fe600..fd85da78 100644 --- a/README.md +++ b/README.md @@ -516,6 +516,19 @@ Fast, modern, secure VPN tunnel [:books: WireGuard add-on documentation][addon-doc-wireguard] +### ✓ [Z-Wave JS to MQTT][addon-zwavejs2mqtt] + +![Latest Version][zwavejs2mqtt-version-shield] +![Supports armhf Architecture][zwavejs2mqtt-armhf-shield] +![Supports armv7 Architecture][zwavejs2mqtt-armv7-shield] +![Supports aarch64 Architecture][zwavejs2mqtt-aarch64-shield] +![Supports amd64 Architecture][zwavejs2mqtt-amd64-shield] +![Supports i386 Architecture][zwavejs2mqtt-i386-shield] + +Fully configurable Z-Wave JS to MQTT gateway and control panel + +[:books: Z-Wave JS to MQTT add-on documentation][addon-doc-zwavejs2mqtt] + ### ✓ [Z-Wave to MQTT][addon-zwave2mqtt] ![Latest Version][zwave2mqtt-version-shield] @@ -643,6 +656,7 @@ on the correct GitHub repository matching the add-on. - [Open an issue for the add-on: UniFi Controller][unifi-issue] - [Open an issue for the add-on: Visual Studio Code][vscode-issue] - [Open an issue for the add-on: WireGuard][wireguard-issue] +- [Open an issue for the add-on: Z-Wave JS to MQTT][zwavejs2mqtt-issue] - [Open an issue for the add-on: Z-Wave to MQTT][zwave2mqtt-issue] - [Open an issue for the add-on: ZeroTier One][zerotier-issue] - [Open an issue for the add-on: chrony][chrony-issue] @@ -1028,6 +1042,15 @@ SOFTWARE. [wireguard-armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg [wireguard-armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg [wireguard-i386-shield]: https://img.shields.io/badge/i386-yes-green.svg +[addon-zwavejs2mqtt]: https://github.com/hassio-addons/addon-zwavejs2mqtt/tree/v0.1.0 +[addon-doc-zwavejs2mqtt]: https://github.com/hassio-addons/addon-zwavejs2mqtt/blob/v0.1.0/README.md +[zwavejs2mqtt-issue]: https://github.com/hassio-addons/addon-zwavejs2mqtt/issues +[zwavejs2mqtt-version-shield]: https://img.shields.io/badge/version-v0.1.0-blue.svg +[zwavejs2mqtt-aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg +[zwavejs2mqtt-amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg +[zwavejs2mqtt-armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg +[zwavejs2mqtt-armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg +[zwavejs2mqtt-i386-shield]: https://img.shields.io/badge/i386-yes-green.svg [addon-zwave2mqtt]: https://github.com/hassio-addons/addon-zwave2mqtt/tree/v0.9.0 [addon-doc-zwave2mqtt]: https://github.com/hassio-addons/addon-zwave2mqtt/blob/v0.9.0/README.md [zwave2mqtt-issue]: https://github.com/hassio-addons/addon-zwave2mqtt/issues diff --git a/zwavejs2mqtt/CHANGELOG.md b/zwavejs2mqtt/CHANGELOG.md new file mode 100644 index 00000000..c4cdea74 --- /dev/null +++ b/zwavejs2mqtt/CHANGELOG.md @@ -0,0 +1,11 @@ +## Whatโ€™s changed + +The initial release of the Z-Wave JS to MQTT add-on ๐ŸŽ‰ + +## โœจ New features + +- Add initial add-on code @frenck (#1) + +## ๐Ÿ“š Documentation + +- Extend setup instructions @frenck (#2) diff --git a/zwavejs2mqtt/DOCS.md b/zwavejs2mqtt/DOCS.md new file mode 100644 index 00000000..0bab822d --- /dev/null +++ b/zwavejs2mqtt/DOCS.md @@ -0,0 +1,182 @@ +# Home Assistant Community Add-on: Z-Wave JS to MQTT + +The Z-Wave JS to MQTT add-on allows you to decouple your Z-Wave network from +your Home Assistant instance by leveraging your MQTT broker. It ships with +a web-based control panel, allowing you to configure every aspect of your +Z-Wave network and how they are published in MQTT. + +Some advantages and use-cases for this are: + +- Compatible with the Home Assistant Z-Wave JS integration. +- Your Z-Wave network will keep running between Home Assistant restarts. +- You can directly use things like Node-RED with your Z-Wave network, while + it is available for Home Assistant at the same time. +- Allow [ESPHome.io][esphome] based ESP devices to directly respond or work + with your Z-Wave network. + +This add-on uses the [Zwavejs2Mqtt][zwavejs2mqtt] software. + +## Installation + +The installation of this add-on is pretty straightforward and not different in +comparison to installing any other Home Assistant add-on. + +1. Search for the "Z-Wave JS to MQTT" add-on in the Supervisor add-on store + and install it. +1. Start the "Z-Wave JS to MQTT" add-on. +1. Check the logs of the "Z-Wave JS to MQTT" add-on to see if everything went + well. +1. Click the "OPEN WEB UI" button. +1. Enjoy the add-on! + +**NOTE**: The upstream project has documentation on using the software itself: + + +## Setting up the Home Assistant Z-Wave JS integration + +By default the Home Assistant Z-Wave JS integration will try to set up the +official "Z-Wave JS" add-on from the official add-on store. + +**It is recommended to use the official add-on instead of this one!** + +However, this add-on will provide an add-on UI and has the ability to +send/receive data over MQTT as well. So, if that is your thing, this +add-on might be for you. + +After starting the add-on successfully, it is time to hook it up with +Home Assistant. + +To do this: + +1. Open the Z-Wave JS to MQTT control panel by clikcing the "OPEN WEB UI" + button on the add-on page in the Supervisor. +1. In the control panel, go to "Settings" in the menu and click on the "Zwave" + bar that shows up on the right. +1. Enter the following information: + - Serial Port (e.g., `/dev/serial/by-id/usb-0658_0200_if00`) + - Network Key (e.g., `2232666D100F795E5BB17F0A1BB7A146`) + - **Enable the WS Server** checkbox! + +You can check the "Disable Gateway" box for now, as you can set up MQTT +later (if you like that is). + +Now click the "SAVE" button and navigate to the "Control Panel" in the menu. +If you had devices paired already, you should see the showing up slowly. + +Now it is time to set up Home Assistant: + +1. Go to the Configuration panel and click "Integrations". +1. In the bottom left, click "+ Add Integration". +1. Select the "Z-Wave JS" integration from the list. +1. A dialog box will show, asking to use the add-on: + - **UNCHECK** that box, it will install the officia add-on. + - Again, the official add-on is recommended, so... +1. In the next dialog it will ask for the server. Enter: + `ws://a0d7b954-zwavejs2mqtt:3000` +1. Confirm and done! + +## Configuration + +**Note**: _Remember to restart the add-on when the configuration is changed._ + +Example add-on configuration: + +```yaml +log_level: info +``` + +### Option: `log_level` + +The `log_level` option controls the level of log output by the addon and can +be changed to be more or less verbose, which might be useful when you are +dealing with an unknown issue. Possible values are: + +- `trace`: Show every detail, like all called internal functions. +- `debug`: Shows detailed debug information. +- `info`: Normal (usually) interesting events. +- `warning`: Exceptional occurrences that are not errors. +- `error`: Runtime errors that do not require immediate action. +- `fatal`: Something went terribly wrong. Add-on becomes unusable. + +Please note that each level automatically includes log messages from a +more severe level, e.g., `debug` also shows `info` messages. By default, +the `log_level` is set to `info`, which is the recommended setting unless +you are troubleshooting. + +## Known issues and limitations + +- Z-Wave JS to MQTT supports Home Assistant Discovery over MQTT. It is + **STRONGLY** recommended **NOT** to use that option. Use the Z-Wave JS + integration as documented above instead. + +## Changelog & Releases + +This repository keeps a change log using [GitHub's releases][releases] +functionality. + +Releases are based on [Semantic Versioning][semver], and use the format +of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented +based on the following: + +- `MAJOR`: Incompatible or major changes. +- `MINOR`: Backwards-compatible new features and enhancements. +- `PATCH`: Backwards-compatible bugfixes and package updates. + +## Support + +Got questions? + +You have several options to get them answered: + +- The [Home Assistant Community Add-ons Discord chat server][discord] for add-on + support and feature requests. +- The [Home Assistant Discord chat server][discord-ha] for general Home + Assistant discussions and questions. +- The Home Assistant [Community Forum][forum]. +- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit] + +You could also [open an issue here][issue] GitHub. + +## Authors & contributors + +The original setup of this repository is by [Franck Nijhof][frenck]. + +For a full list of all authors and contributors, +check [the contributor's page][contributors]. + +## License + +MIT License + +Copyright (c) 2021 Franck Nijhof + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +[contributors]: https://github.com/hassio-addons/addon-zwavejs2mqtt/graphs/contributors +[discord-ha]: https://discord.gg/c5DvZ4e +[discord]: https://discord.me/hassioaddons +[esphome]: https://esphome.io/components/mqtt.html#on-message-trigger +[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg +[forum]: https://community.home-assistant.io/?u=frenck +[frenck]: https://github.com/frenck +[issue]: https://github.com/hassio-addons/addon-zwavejs2mqtt/issues +[reddit]: https://reddit.com/r/homeassistant +[releases]: https://github.com/hassio-addons/addon-zwavejs2mqtt/releases +[semver]: http://semver.org/spec/v2.0.0.htm +[zwavejs2mqtt]: https://github.com/zwave-js/zwavejs2mqtt diff --git a/zwavejs2mqtt/README.md b/zwavejs2mqtt/README.md new file mode 100644 index 00000000..09e2a67c --- /dev/null +++ b/zwavejs2mqtt/README.md @@ -0,0 +1,44 @@ +# Home Assistant Community Add-on: Z-Wave JS to MQTT + +[![Release][release-shield]][release] ![Project Stage][project-stage-shield] ![Project Maintenance][maintenance-shield] + +[![Discord][discord-shield]][discord] [![Community Forum][forum-shield]][forum] + +[![Sponsor Frenck via GitHub Sponsors][github-sponsors-shield]][github-sponsors] + +[![Support Frenck on Patreon][patreon-shield]][patreon] + +Fully configurable Z-Wave JS to MQTT gateway and control panel. + +![Z-Wave JS to MQTT][logo] + +## About + +The Z-Wave JS to MQTT add-on allows you to decouple your Z-Wave network from +your Home Assistant instance by leveraging your MQTT broker. It ships with +a web-based control panel, allowing you to configure every aspect of your +Z-Wave network and how they are published in MQTT. + +Some advantages and use-cases for this are: + +- Compatible with the Home Assistant Z-Wave JS integration. +- Your Z-Wave network will keep running between Home Assistant restarts. +- You can directly use things like Node-RED with your Z-Wave network, while + it is available for Home Assistant at the same time. +- Allow [ESPHome.io][esphome] based ESP devices to directly respond or work + with your Z-Wave network. + +[discord-shield]: https://img.shields.io/discord/478094546522079232.svg +[discord]: https://discord.me/hassioaddons +[esphome]: https://esphome.io/components/mqtt.html#on-message-trigger +[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg +[forum]: https://community.home-assistant.io/?u=frenck +[github-sponsors-shield]: https://frenck.dev/wp-content/uploads/2019/12/github_sponsor.png +[github-sponsors]: https://github.com/sponsors/frenck +[logo]: https://github.com/hassio-addons/addon-zwavejs2mqtt/raw/main/zwavejs2mqtt/logo.png +[maintenance-shield]: https://img.shields.io/maintenance/yes/2021.svg +[patreon-shield]: https://frenck.dev/wp-content/uploads/2019/12/patreon.png +[patreon]: https://www.patreon.com/frenck +[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg +[release-shield]: https://img.shields.io/badge/version-v0.1.0-blue.svg +[release]: https://github.com/hassio-addons/addon-zwavejs2mqtt/tree/v0.1.0 \ No newline at end of file diff --git a/zwavejs2mqtt/config.json b/zwavejs2mqtt/config.json new file mode 100644 index 00000000..068c0a2f --- /dev/null +++ b/zwavejs2mqtt/config.json @@ -0,0 +1,30 @@ +{ + "name": "Z-Wave JS to MQTT", + "version": "0.1.0", + "slug": "zwavejs2mqtt", + "description": "Fully configurable Z-Wave JS to MQTT gateway and control panel", + "url": "https://github.com/hassio-addons/addon-zwavejs2mqtt", + "ingress": true, + "panel_title": "Z-Wave JS", + "panel_icon": "mdi:z-wave", + "startup": "system", + "init": false, + "arch": [ + "aarch64", + "amd64", + "armhf", + "armv7", + "i386" + ], + "discovery": [ + "zwave_js" + ], + "auto_uart": true, + "map": [ + "share:rw" + ], + "schema": { + "log_level": "list(trace|debug|info|notice|warning|error|fatal)?" + }, + "image": "ghcr.io/hassio-addons/zwavejs2mqtt/{arch}" +} \ No newline at end of file diff --git a/zwavejs2mqtt/icon.png b/zwavejs2mqtt/icon.png new file mode 100644 index 00000000..360d704d Binary files /dev/null and b/zwavejs2mqtt/icon.png differ diff --git a/zwavejs2mqtt/logo.png b/zwavejs2mqtt/logo.png new file mode 100644 index 00000000..a5933418 Binary files /dev/null and b/zwavejs2mqtt/logo.png differ