mirror of
https://github.com/aljazceru/addons.git
synced 2025-12-18 13:44:20 +01:00
f3f8ac2b80
Co-authored-by: Martin Hjelmare <marhje52@gmail.com> Co-authored-by: Fabian Affolter <mail@fabian-affolter.ch>
180 lines
6.6 KiB
Markdown
180 lines
6.6 KiB
Markdown
# Home Assistant Add-on: OpenZWave
|
|
|
|
## Installation
|
|
|
|
Follow these steps to get the add-on installed on your system:
|
|
|
|
1. Navigate in your Home Assistant frontend to **Supervisor** -> **Add-on Store**.
|
|
2. Find the "OpenZWave" add-on and click it.
|
|
3. Click on the "INSTALL" button.
|
|
4. This add-on currently requires to have the Mosquitto add-on installed.
|
|
Please make sure to install and set up that add-on before continuing.
|
|
|
|
## How to use
|
|
|
|
The add-on needs to know where your Z-Wave stick can be found, and therefore,
|
|
you'll need to configure the add-on to point to the right device.
|
|
|
|
If you're using Home Assistant you may find the correct value for this on the
|
|
`Supervisor -> System -> Host system -> Hardware` page. It is recommended
|
|
to use a "by-id" path to the device if one exists, as it is not subject to
|
|
change if other devices are added to the system.
|
|
|
|
1. Replace `null` in the `device` option in the add-on configuration and specify
|
|
the device name in quotes: e.g., something like
|
|
`"/dev/serial/by-id/usb-0658_0200-if00"`,
|
|
`"/dev/ttyUSB0"`, `"/dev/ttyAMA0"`, or `"/dev/ttyACM0"`.
|
|
2. Set your 16-byte network key in the form `0x01, 0x02...` used in order to
|
|
connect securely to compatible devices. It is recommended that a network key
|
|
is configured as security enabled devices may not function correctly if they
|
|
are not added securely.
|
|
3. Click on "SAVE" to save the add-on configuration.
|
|
4. Start the add-on.
|
|
5. Add the OpenZWave integration to Home Assistant, see documentation:
|
|
<https://www.home-assistant.io/integrations/ozw>
|
|
|
|
After installing and starting this add-on, access the ozw-admin interface using
|
|
the "OPEN WEBUI" button.
|
|
|
|
## Configuration
|
|
|
|
Add-on configuration:
|
|
|
|
```yaml
|
|
device: /dev/ttyUSB0
|
|
network_key: 0x2e, 0xcc, 0xab, 0x1c, 0xa3, 0x7f, 0x0e, 0xb5, 0x70, 0x71, 0x2d, 0x98, 0x25, 0x43, 0xee, 0x0c
|
|
instance: 1
|
|
```
|
|
|
|
### Option `device`
|
|
|
|
The device address of your Z-Wave controller.
|
|
|
|
If you're using Home Assistant you may find the correct value for this on the
|
|
`Supervisor -> System -> Host system -> Hardware` page. It is recommended
|
|
to use a "by-id" path to the device if one exists, as it is not subject to
|
|
change if other devices are added to the system.
|
|
|
|
In most cases this looks like one of the following:
|
|
|
|
- `"/dev/serial/by-id/usb-0658_0200-if00"`
|
|
- `"/dev/ttyUSB0"`
|
|
- `"/dev/ttyAMA0"`
|
|
- `"/dev/ttyACM0"`
|
|
|
|
### Option `network_key`
|
|
|
|
Security Z-Wave devices require a network key before being added to the network.
|
|
You must set the `network_key` configuration option to use a network key before
|
|
adding these devices.
|
|
|
|
To generate a network key, you can use the following script in, e.g., the SSH
|
|
add-on:
|
|
|
|
```bash
|
|
cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'
|
|
```
|
|
|
|
You can also use sites like this one to generate the required data,
|
|
just remember to put `0x` before each pair of characters:
|
|
|
|
<https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h>
|
|
|
|
Ensure you keep a backup of this key. If you have to rebuild your system and
|
|
don't have a backup of this key, you won't be able to reconnect to any security
|
|
devices. This may mean you have to do a factory reset on those devices, and your
|
|
controller, before rebuilding your Z-Wave network.
|
|
|
|
### Option `instance` (optional)
|
|
|
|
Z-Wave instance number as reported to MQTT. This corresponds with the
|
|
`instance_id` attribute of `ozw` services in Home Assistant.
|
|
|
|
The instance ID defaults to `1`, which is generally fine to keep and use.
|
|
Only change this in case you are using multiple instances on the same MQTT
|
|
server.
|
|
|
|
## Accessing the ozw-admin application
|
|
|
|
The add-on allows you to access the underlying ozw-admin application running
|
|
in this add-on. This allows you to view, configure and control your Z-Wave
|
|
network and its devices.
|
|
|
|
### Accessing the ozw-admin application via Ingress
|
|
|
|
You can access the built-in ozw-admin application directly via Home Assistant
|
|
Ingress. Click on the "OPEN WEBUI" button to access it.
|
|
|
|
If it does not auto connect to your Z-Wave network automatically:
|
|
Click on the "Open" button in the menu bar of the application and click on
|
|
the start button in the **"Remote OZWDaemon"** section.
|
|
|
|
If you need to access the application more often, it can be added to the
|
|
Home Assistant sidebar by toggling the "Show in sidebar" switch on the
|
|
add-on page.
|
|
|
|
### Accessing the ozw-admin application via VNC
|
|
|
|
You can access the built-in ozw-admin application via a VNC viewer.
|
|
|
|
Please note, you can access the same interface using the "OPEN WEBUI" button,
|
|
described above.
|
|
|
|
To enable it:
|
|
|
|
- Set a port number for VNC in the "Network" configuration section of the
|
|
add-on and hit "SAVE". Advised is to use port 5900, but any other port above
|
|
5900 works as well.
|
|
- Restart the add-on.
|
|
|
|
To access it, you need a [VNC Viewer][vnc-viewer] application. If you are using
|
|
macOS, you are in luck, since VNC is built-in. Open the spotlight search and
|
|
enter the VNC service URL.
|
|
|
|
The VNC service URL looks like [vnc://homeassistant.local:5900](vnc-service-url).
|
|
Adjust port and possibly hostname if you've changed it in Home Assistant host system
|
|
settings.
|
|
|
|
### Connecting remotely using a local ozw-admin application
|
|
|
|
Alternatively, the ozw-admin application can be downloaded and installed on a
|
|
remote machine, like your desktop computer. To connect your remote machine:
|
|
|
|
- Set a port number for the ozw-admin in the "Network" configuration section of
|
|
the add-on and hit "SAVE". Advised is to use port 1983, as this is the default.
|
|
- Restart the add-on.
|
|
|
|
To access your Z-Wave network with the ozw-admin, you need to first download the ozw-admin application. The latest
|
|
version can be found here:
|
|
|
|
<http://bamboo.my-ho.st/bamboo/browse/OZW-OZW/latestSuccessful/artifact>
|
|
|
|
After you've installed and started the ozw-admin application, click "Open"
|
|
and set the remote host and port in the "Remote OZWDaemon" section.
|
|
For example, host: `homeassistant.local`, with port `1983` in the second field.
|
|
|
|
Next, click on "Start" to connect.
|
|
|
|
## Known issues and limitations
|
|
|
|
- Your hardware needs to be compatible with OpenZWave library
|
|
|
|
## Support
|
|
|
|
Got questions?
|
|
|
|
You have several options to get them answered:
|
|
|
|
- The [Home Assistant Discord Chat Server][discord].
|
|
- The Home Assistant [Community Forum][forum].
|
|
- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit]
|
|
|
|
In case you've found a bug, please [open an issue on our GitHub][issue].
|
|
|
|
[discord]: https://discord.gg/c5DvZ4e
|
|
[forum]: https://community.home-assistant.io
|
|
[issue]: https://github.com/home-assistant/hassio-addons/issues
|
|
[reddit]: https://reddit.com/r/homeassistant
|
|
[vnc-service-url]: vnc://homeassistant.local:5900
|
|
[vnc-viewer]: https://bintray.com/tigervnc/stable/tigervnc/
|