openHAB

# Z-Wave JS Binding

The zwavejs binding integrates Z-Wave JS with openHAB, allowing you to control and monitor Z-Wave devices using the Z-Wave JS web service (part of Z-Wave JS UI). This binding supports a wide range of Z-Wave devices, including sensors, switches, dimmers, and more. For documentation about Z-Wave JS UI, please visit the Z-Wave JS UI documentation (opens new window).

# Prerequisites

Before using the zwavejs binding, ensure the following prerequisites are met:

  • You have a running instance of Z-Wave JS (opens new window).
  • Your Z-Wave controller is properly connected and recognized by Z-Wave JS.
  • The Z-Wave JS instance has the web service (WebSocket server) enabled (Settings → Home Assistant → WS Server).
  • Network connectivity exists between openHAB and the Z-Wave JS Webservice (the hostname and port must be reachable from openHAB).

Note: If you are transitioning from the native Z-Wave binding to the zwavejs binding, you can safely test this binding without permanently affecting your setup. All node information will remain on your controller as usual. However, please avoid performing a manual reset unless absolutely necessary, as it may complicate reverting to the native binding.

# Supported Things

This binding supports the following types of things:

  • gateway: Represents the Z-Wave JS web service bridge. This is required to communicate with the Z-Wave network.
  • node: Represents a Z-Wave device (node) in the network. Each node can have multiple channels corresponding to its capabilities.

Note: This binding does not maintain a Z-Wave device database and relies on the external Z-Wave JS project for device compatibility and functionality.

# Discovery

The zwavejs binding supports automatic discovery of Z-Wave devices. When the bridge is added and connected, it will automatically discover and add Z-Wave nodes to the openHAB system. The following discovery features are available:

  • Automatic discovery of Z-Wave nodes when they are added to the network.
  • Automatic update of node information when the node is updated in the Z-Wave network.

# Bridge Configuration

The zwavejs binding requires configuration of the bridge to connect to the Z-Wave JS web service. The configuration options include:

Name Type Description Default Required Advanced
hostname text Hostname or IP address of the server N/A yes no
port integer Port number to access the service 3000 yes no
maxMessageSize integer Maximum size of messages in bytes 16777216 no yes
configurationChannels boolean Expose the Command Class "Configuration" as channels false no yes

# Thing Configuration

Each Z-Wave node can have its own configuration options. All configuration parameters are set by the binding during startup and are read-only. Only the advanced parameter id can (optionally) be set in the Thing configuration in the openHAB UI or in the .things file.

# Channels

Z-Wave nodes can have multiple channels corresponding to their capabilities. The channels can be linked to items in openHAB to control and monitor the device. These channels are dynamically added to the Thing during node initialization; therefore, there is no list of possible channels in this documentation.

# Statistics Channels

Every node has an advanced statistics channel group with the following read-only channels:

Channel Item type Description
last-seen DateTime Last time a message was received from the node
last-awake DateTime Last time the node was awake
commands-tx Number Commands sent to the node
commands-rx Number Commands received from the node
commands-dropped-tx Number Commands to the node that were dropped
commands-dropped-rx Number Commands from the node that were dropped
timeout-response Number Commands for which no response was received
rtt Number:Time Average round-trip time
rssi Number:Power Signal strength of the last received message

Optional statistics remain undefined until they are supplied by Z-Wave JS. last-awake is updated when the binding receives a node wake-up event. The current Z-Wave JS Server WebSocket schema does not expose the persisted last-awake value, so this channel is not restored when the binding starts.

# Notification-Virtual Channel

The binding automatically adds a notification-virtual channel for endpoints that have both a Notification (Alarm) and a Door Lock command class. This virtual channel is designed to provide a unified state update when a notification event occurs. It provides the event payload in JSON as a string value. A common scenario is using this JSON to determine the userId that unlocked a door lock. This channel is added automatically; no manual configuration is required.

# Channel Configuration and Inversion

Channels in the zwavejs binding support an inversion configuration option. This feature allows you to reverse the logical behavior of a channel, which is particularly useful for devices where the default open/close, on/off, or up/down logic does not align with your installation or preferences. The following devices and parameters support inversion:

  • Switch, Contact, and Dimmer: These channels have a single configuration parameter, inverted, which reverses the logical state.
  • RollerShutter: These channels have two configuration parameters:
    • inverted: Reverses the logical state, similar to the above.
    • isUpDownInverted: Independently inverts the up and down directions.

note: Without any inversion, the binding considers 100% fully open (up position) and 0% fully closed (down position).

# Full Example

# demo.things Example

Bridge zwavejs:gateway:myBridge "Z-Wave JS Bridge" [ hostname="localhost", port=3000 ] {
    Thing node node1 "Z-Wave Node 1" [ id=1 ]
    Thing node node2 "Z-Wave Node 2" [ id=2 ]
}

# demo.items Example

Switch LightSwitch "Light Switch" { channel="zwavejs:node:myBridge:node1:binary-switch-value" }

# Troubleshooting

If you encounter issues with the zwavejs binding, check the following:

  • Ensure the Z-Wave JS web service is running and accessible at the configured hostname and port.
  • Check the openHAB logs for any error messages related to the zwavejs binding.
  • Verify the configuration of the bridge and nodes in the openHAB UI or configuration files.

For further assistance, refer to the openHAB community forums or the Z-Wave JS documentation.

# Resources

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Z-Way →