Z-Wave JS UI

You can execute custom driver functions on a schedule using the Scheduled Jobs table. Jobs use standard cron expressions.

Properties:

• Name: Job identifier.
• Enabled: Toggle the job.
• On Init: Run the job immediately upon gateway initialization.
• Cron: The schedule (e.g., 0 0 * * * for daily at midnight).
• Code: The valid driver function code to execute.

Z-Wave JS UI automatically creates sensor, cover, binary_sensor, and switch components. For complex types like climate or fan, you must define custom configurations.

Setup

1. Create a file named customDevices.js or customDevices.json in the store folder.
2. The file must exist before application startup, or you must restart the application after creating it.

Configuration Format

The key is the Z-Wave device id (<manufacturerid>-<productid>-<producttype>). The value is an array of Home Assistant component objects.

To find a specific node's Device id:

1. Go to the Control Panel.
2. Select a node in the table.
3. Select the Node tab.
4. The ID is displayed under the Node Actions dropdown menu.

When publishing updates via MQTT, you can choose from three payload formats:

JSON Time-Value

Best for time-series databases. Contains a timestamp and the value.

{
  "time": 1548683523859,
  "value": 10
}

Entire ValueId Object

Contains full metadata about the Z-Wave value. Useful for deep inspection.

{
  id: "38-0-targetValue",
  nodeId: 8,
  commandClass: 38,
  commandClassName: "Multilevel Switch",
  endpoint: 0,
  property: "targetValue",
  propertyName: "targetValue",
  propertyKey: undefined,
  type: "number",
  readable: true,
  writeable: true,
  description: undefined,
  label: "Target value",
  default: undefined,
  genre: "user",
  min: 0,
  max: 99,
  step: undefined,
  unit: undefined,
  list: false,
  value: undefined,
  lastUpdate: 1604044669393,
}

Just value

Contains only the raw Numeric, String, or Bool value.

Plugins are NodeJS packages that extend Z-Wave JS UI by providing access to the Z-Wave client, MQTT client, and the Express application instance.

Plugins are loaded using ES dynamic import() and must export a default class. The lifecycle of a plugin is managed by the application: the constructor is called when the plugin is loaded, and the destroy() method is called when the application shuts down or settings are updated. This allows plugins to clean up event listeners, intervals, or other stateful resources.

interface PluginContext {
  zwave: ZwaveClient
  mqtt: MqttClient
  app: Router       // Express router
  logger: ModuleLogger
}

interface CustomPlugin extends PluginContext {
  name: string
  destroy(): Promise<void>
}

Z-Wave JS UI provides access to almost all Z-Wave JS APIs (and additional features) through MQTT.

When constructing your MQTT topics, use the mqtt_name wildcard, which corresponds to the sanitized name defined in your MQTT Settings.

Events in Z-Wave JS UI are organized into channels. To receive events, you must explicitly subscribe to them. Subscriptions are additive; calling SUBSCRIBE with new channels adds them to your current list rather than replacing it.

Subscribing

Send a SUBSCRIBE event with an array of channel names. You can use an acknowledgement callback to verify your active subscriptions.

Unsubscribing

Send an UNSUBSCRIBE event with an array of channel names to stop receiving events for those specific channels.

Subscribe to all channels

Use the special keyword all to subscribe to every available channel at once.

When adding values to the Gateway values table, the UI shows only one device for each type. This is a feature designed to speed up network setup.

By adding the specific values you want to bridge to MQTT for a single device of a certain type (e.g., a single light switch for an 'on/off' command), Z-Wave JS UI will automatically bridge those same values for all other devices of that same type in your network, avoiding the need for manual per-device configuration.

The type of health check performed via the DIAGNOSE button depends on the target node selected in the Network Graph:

• Lifeline healthcheck: Performed when the target node is the controller. This checks the connection between the node and the controller.
• Route healthcheck: Performed when the target node is any other node in the network. This checks the routing paths for that specific node.

Note that Route healthcheck results may vary in detail depending on the specific capabilities and support of the node being checked. If results are unclear, click the ? button in the dialog for a detailed explanation of the findings.