# 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) security keys in the form `2232666D1...`
   in order to connect securely to compatible devices. It is recommended
   that all four network keys are 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 they support S2 security
       as the S0 security 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:

```yaml
device: /dev/ttyUSB0
s0_legacy_key: 2232666D100F795E5BB17F0A1BB7A146
s2_access_control_key: A97D2A51A6D4022998BEFC7B5DAE8EA1
s2_authenticated_key: 309D4AAEF63EFD85967D76ECA014D1DF
s2_unauthenticated_key: CF338FE0CB99549F7C0EA96308E5A403
```

### 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"`

### Security Keys

There are four different security keys required to take full advantage of the
different inclusion methods that Z-Wave JS supports: `s0_legacy_key`,
`s2_access_control_key`, `s2_authenticated_key`, and `s2_unauthenticated_key`.

If you are coming from a previous version of `zwave-js`, you likely have a key
stored in the `network_key` configuration option. When the addon is first
started, the key will be migrated from `network_key` to `s0_legacy_key` which
will ensure that your S0 secured devices will continue to function.

If any of these keys are missing on startup, the addon will autogenerate one for
you. To generate a network key manually, you can use the following script in,
e.g., the SSH add-on:

```bash
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 these keys. If you have to rebuild your system and
don't have a backup of these keys, you won't be able to communicate 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.

> NOTE: Sharing keys between multiple security classes is a security risk, so
> if you choose to configure these keys on your own, be sure to make them
> unique!

#### Option `s0_legacy_key`

S0 Security Z-Wave devices require a network key before being added to the network.
This configuration option is required, but if it is unset the addon will generate
a new one automatically on startup.

#### Option `s2_access_control_key`

The `s2_access_control_key` must be provided in order to include devices with the
S2 Access Control security class. This security class is needed by devices such
as door locks and garage door openers. This configuration option is required,
but if it is unset the addon will generate a new one automatically on startup.

#### Option `s2_authenticated_key`

The `s2_authenticated_key` must be provided in order to include devices with
the S2 Authenticated security class. Devices such as security systems, sensors,
lighting, etc. can request this security class. This configuration option is
required, but if it is unset the addon will generate a new one automatically
on startup.

### Option `s2_unauthenticated_key`

The `s2_unauthenticated_key` must be provided in order to include devices with
the S2 Unauthenticated security class. This is similar to S2 Authenticated, but
without verification that the correct device was included. This configuration
option is required, but if it is unset the addon will generate a new one
automatically on startup.

### 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.

### Option `network_key` (deprecated)

In previous versions of the addon, this was the only key that was needed. With
the introduction of S2 security inclusion in zwave-js, this option has been
deprecated in favor of `s0_legacy_key`. If still set, the `network_key` value will be
migrated to `s0_legacy_key` on first startup.

## 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][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