addons/zwave_js/DOCS.md

Home Assistant Add-on: Z-Wave JS

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 "Z-Wave JS" add-on and click it.
3. Click on the "INSTALL" button.

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 (32 character hex) network key in the form 2232666D1... used in order to connect securely to compatible devices. It is recommended that a network key is configured as some security enabled devices (locks, etc) may not function correctly if they are not added securely.
   • As a note, it is not recommended to securely connect all devices unless necessary as it triples the amount of messages sent on the mesh.
3. Click on "SAVE" to save the add-on configuration.
4. Start the add-on.
5. Add the Z-Wave JS integration to Home Assistant, see documentation: https://www.home-assistant.io/integrations/zwave_js

Configuration

Add-on configuration:

device: /dev/ttyUSB0
network_key: 2232666D100F795E5BB17F0A1BB7A146

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.

If you don't add a network key, it will autogenerate one for you.

To generate a network key manually, you can use the following script in, e.g., the SSH add-on:

hexdump -n 16 -e '4/4 "%08X" 1 "\n"' /dev/random

You can also use sites like this one to generate the required data:

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 securely included devices. This may mean you have to do a factory reset on those devices and your controller, before rebuilding your Z-Wave network.

Option log_level (optional)

This option sets the log level of Z-Wave JS. Valid options are:

• silly
• debug
• verbose
• http
• info
• warn
• error

If no log_level is specified, the log level will be set to the level set in the Supervisor.

Option emulate_hardware (optional)

If you don't have a USB stick, you can use a fake stick for testing purposes. It will not be able to control any real devices.

Known issues and limitations

• Your hardware needs to be compatible with the Z-Wave JS library

Support

Got questions?

You have several options to get them answered:

• The Home Assistant Discord Chat Server.
• The Home Assistant Community Forum.
• Join the Reddit subreddit in /r/homeassistant

In case you've found a bug, please open an issue on our GitHub.