Z-Wave

The Z-Wave page manages Z-Wave wireless device networks. You can enroll (include) and remove (exclude) Z-Wave devices, create GEM zones from Z-Wave nodes, configure command class values, and set up command and response mappings between Z-Wave value IDs and GEM zone commands/attributes.

Prerequisites

Create a Z-Wave controller device in System > Devices with the driver set to zwave and Enabled set to Yes. Configure the serial port for the Z-Wave USB stick (e.g., /dev/ttyUSB0).

:::tip USB serial path stability On connect, the driver automatically promotes a /dev/tty* address to its stable /dev/serial/by-id/... symlink so the controller survives replug/reboot reordering. If the configured path no longer exists (e.g., the dongle was moved to a different USB port), the driver scans known Z-Wave USB descriptors (Aeotec Z-Stick, Zooz, Nortek HubZ -if00, etc.) and points itself at a matching candidate, persisting the new address on the device row. Disable this behavior by setting the usb_auto_discover attribute on the device to false — recommended only for hosts running multiple identical Z-Wave controllers where the wrong one might be picked up. :::

Page Layout

The page uses a two-panel layout (not tabs). At the top is a controller section with enrollment and removal controls. Below that, the main content area is split into a Nodes panel on the left (35% width) and a Node Configuration panel on the right.

---

Controller Section

Controller Selector

A dropdown at the top lists all Z-Wave controller devices (devices with the zwave driver). Each entry shows the device ID, name, and address. Select a controller to load its Z-Wave nodes and enable the enrollment/removal controls.

Enrollment and Removal Controls

These controls appear after selecting a controller:

Control Group	Button	Description
Enrollment	Start	Begins Z-Wave inclusion mode. The controller listens for new devices to pair. A confirmation prompt appears before starting.
Enrollment	Stop	Stops inclusion mode. Disabled until enrollment is started.
Removal	Start	Begins Z-Wave exclusion mode. The controller listens for devices to remove. A confirmation prompt appears before starting.
Removal	Stop	Stops exclusion mode. Disabled until removal is started.
	Reset	Performs a soft reset of the Z-Wave controller.

note

While enrollment is active, the removal Start button is disabled, and vice versa. Toast messages notify you of inclusion/exclusion events such as "node added," "node removed," or failure messages.

Enrolling a New Device

1. Select your Z-Wave controller from the dropdown.
2. Click Start in the Enrollment group.
3. Confirm the prompt.
4. On the physical Z-Wave device, press the inclusion button (typically triple-tap the paddle or press a small button).
5. Wait for the device to pair (10-60 seconds). A toast message confirms when the node is added.
6. Click Stop to end enrollment, or it will stop automatically after the device pairs.

Removing a Device

1. Select your Z-Wave controller from the dropdown.
2. Click Start in the Removal group.
3. Confirm the prompt.
4. On the physical Z-Wave device, press the exclusion button.
5. Wait for the device to be removed. A toast message confirms when the node is removed.
6. Click Stop to end removal mode.

tip

Exclusion works even on devices that were paired to a different controller. This is useful for factory resetting Z-Wave devices before re-enrolling them.

---

Nodes Panel (Left)

The left panel displays a list of all Z-Wave nodes on the selected controller's network. The panel header shows "Z-Wave Nodes" and has a refresh icon to reload the node list.

Each node in the list shows:

• Node ID in brackets (e.g., [5])
• Manufacturer name
• Description of the device

This is a multi-select list. Click a single node to select it and load its details in the right panel.

warning

You must select exactly one node at a time to view its configuration. If multiple nodes are selected, a warning message appears asking you to select a single node.

---

Node Configuration Panel (Right)

The right panel shows configuration options for the selected Z-Wave node. It contains three sections: Zone Management, Command Class Configuration, and Mappings (the last only appears when a zone is selected).

Zone Management

This section lets you create GEM zones for the selected Z-Wave node or select existing zones.

Existing Zones: A SelectSearch dropdown showing all zones already assigned to this controller and node. Selecting a zone populates the subsystem, endpoint, and control type fields. A Delete button removes the selected zone and all its associated attributes and UI zones (with confirmation).

Below the existing zones selector, there are fields for creating a new zone:

Field	Description
Subsystem	The GEM subsystem for the zone (e.g., lighting, climate, security). Disabled when an existing zone is selected.
Endpoint	The Z-Wave endpoint number. Endpoints represent different functions on multi-channel devices (e.g., a dual-outlet has endpoints 0, 1, 2). Disabled when an existing zone is selected.
Control Type	The control type for the zone (e.g., light_dimmer, light_switch, thermostat). This is a fill-in field that shows all control types currently in use across your system. Disabled when an existing zone is selected.

Click Create Zone to create a new zone. A prompt asks for the zone name (pre-filled with the manufacturer and device label formatted as a lowercase name). The zone is created with the address set to {node_id}:{endpoint}.

Command Class Configuration

This section lets you browse and test Z-Wave command class values for the selected node.

Field	Description
Command Class	A dropdown listing all value IDs for the current node and endpoint. Each entry shows the command class number in brackets, the command class name, the property name, and the endpoint number (e.g., [38] Multilevel Switch currentValue (endpoint 0)).

After selecting a command class value, the metadata is loaded and additional controls appear depending on whether the value is writable or read-only:

For writable values:

• A Value input appears. The input type depends on the value's metadata type:
  • Boolean: A dropdown with true and false options.
  • States: A dropdown listing the predefined state options (e.g., for a thermostat mode: Off, Heat, Cool, Auto).
  • Number/other: A text input matching the metadata type.
• A Test Set button sends the entered value to the Z-Wave device.

For read-only values:

• A "Read-only value" label is shown.
• A Test Get button reads the current value from the Z-Wave device and displays the result.

tip

Use Test Set and Test Get to verify that communication with the Z-Wave device is working correctly before creating command and response mappings.

Mappings

This section appears only when a zone is selected in the Zone Management section above. It uses two sub-tabs: Command Mappings and Response Mappings.

Command Mappings Tab

Command mappings link GEM zone commands (like on, off, set_level) to Z-Wave value IDs and values. When a zone command is triggered, GEM sends the mapped Z-Wave value.

Field	Description
Zone Command	A SelectSearch dropdown of available zone commands for this controller's command set.

1. Select a Command Class value in the Command Class Configuration section above.
2. If the value is writable, enter the desired Value to send.
3. Select a Zone Command from the dropdown.
4. Click Map Command to create the mapping.

The Mapped Commands list below shows all existing command mappings. Each entry displays the zone command name, the linked Z-Wave command class name, property, and value. Each mapped command has:

Icon	Description
Test (remote icon)	Sends the zone command to test the mapping.
Delete (delete icon)	Removes the command mapping.

Response Mappings Tab

Response mappings link Z-Wave value updates to GEM zone attributes. When the Z-Wave device reports a value change, GEM updates the mapped zone attribute.

Field	Description
Attribute Name	A fill-in SelectSearch showing all known zone attribute names. You can select an existing attribute or type a new one.
Map Values	A toggle switch. When enabled, a Key-Value Editor appears where you can define value translations (e.g., mapping Z-Wave numeric states to meaningful strings).

1. Select a Command Class value in the Command Class Configuration section above.
2. Enter or select an Attribute Name (e.g., level, temperature, mode).
3. Optionally enable Map Values and define value translations using the Key-Value Editor.
4. Click Map Response to create the mapping.

The Mapped Responses list below shows all existing response mappings. Each entry displays the attribute name and any value map. Each mapped response has a Delete icon to remove it.

---

Real-Time Updates

The page subscribes to the selected Z-Wave controller for real-time event notifications:

Event	Description
node_added	A new device was enrolled. The node list refreshes automatically.
node_removed	A device was removed. The node list refreshes automatically.
inclusion_started	Enrollment mode is active.
inclusion_stopped	Enrollment mode ended.
exclusion_started	Removal mode is active.
exclusion_stopped	Removal mode ended.
inclusion_failed	Enrollment failed. An error message is shown.
exclusion_failed	Removal failed. An error message is shown.
heal_network_done	Network optimization completed.

Troubleshooting

Enrollment Fails

1. Verify the controller is in inclusion mode (Start button was clicked).
2. Confirm the device is in pairing mode (check manufacturer instructions).
3. Move the device closer to the controller for initial enrollment (within 30 feet).
4. Try removing the device first (exclusion), then re-enrolling.
5. Check that the device is not already paired to another controller.

Device Not Responding

1. Verify the device is powered on.
2. Check that the device is within range of the controller or a repeater node.
3. Reset the controller if communication issues persist.
4. For battery-powered devices, wake the device before configuring.

Value Not Updating

1. Verify the command class value ID mapping is correct.
2. Confirm the Z-Wave device is sending updates.
3. For battery devices, the device must be awake to send updates.
4. Check that the attribute type matches the Z-Wave value type.

Related Documentation

• Devices - Z-Wave controller device configuration
• Zones - Zone configuration
• Command Sets - Zone command definitions