Z-Wave JS Server

Small server wrapper around Z-Wave JS to access it via a WebSocket.

Trying it out

These instructions are for development only. These CLIs will be available as zwave-server and zwave-client after installing the NPM package.

Start server

tsx src/bin/server.ts /dev/tty0

Opens server on ws://0.0.0.0:3000.

You can specify a configuration file with --config. This can be a JSON file or a JS file that exports the config. It needs to follow the Z-Wave JS config format.

NOTE: Unless specificed in the configuration file, the emitValueUpdateAfterSetValue configuration option will be set to true. This is recommended for multi-client setups and for cases where multiple applications are sharing access to the same driver, e.g. zwavejs2mqtt

You can specify a different port for the websocket server to listen on with --port, as well as the interface to attach to using --host, the default host is 0.0.0.0 i.e all interfaces.

If you don't have a USB stick, you can add --mock-driver to use a fake stick.

DNS-SD is enabled in the server by default. If you would like to disable it, add --disable-dns-sd.

Start client

Requires server to be running.

Default connects to ws://localhost:3000:

tsx src/bin/client.ts

To specify different host:

tsx src/bin/client.ts ws://192.168.1.100:6000

To specify that it outputs each message on a single line so it can be replayed later:

tsx src/bin/client.ts --dump

You can filter the output by a specific node ID:

tsx src/bin/client.ts --node 52

To specify a schema version other than the latest (maxSchemaVersion):

tsx src/bin/client.ts --schemaVersion 0

All these options can be combined.

API

When a client connects, the server will send the version.

interface {
  type: "version";
  driverVersion: string;
  serverVersion: string;
  homeId: number;
}

To set the schema version that the client supports as well as an optional user agent that will be added to web requests, the client should send the initialize command.

interface {
  messageId: string;
  command: "initialize";
  schemaVersion: number;
  additionalUserAgentComponents?: Record<string, string>;
}

To start receive the state and get events, the client needs to send the start_listening command.

interface {
  messageId: string;
  command: "start_listening";
}

The server will respond with the current state and start sending events.

interface {
  type: "result";
  messageId: string; // maps the `start_listening` command
  success: true,
  result: {
    state: {
      controller: Partial<ZWaveController>;
      nodes: Partial<ZWaveNode>[];
    }
  };
}

After that, the client will be notified of each state change that happens inside Z-Wave JS.

Event keys follow the names/types as used by Z-Wave JS.

interface {
  type: "event",
  event: {
    source: "driver" | "controller" | "node";
    event: string;
    [key: string]: unknown;
  }
}

Client commands

Server level commands

Start listening to events

interface {
  messageId: string;
  command: "start_listening";
}

Set API schema version

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "set_api_schema";
  schemaVersion: number;
}

Start listening to logging events

[compatible with schema version: 31+]

Start receiving logs as events. Look at the logging event documentation for more information about the events. If filter is included, only logs that match the filter will be sent as events, the rest will be skipped.

interface {
  messageId: string;
  command: "start_listening_logs";
  filter?: Partial<NodeLogContext| DriverLogContext | ControllerLogContext | SerialLogContext | ConfigLogContext>;
}

Stop listening to logging events

[compatible with schema version: 31+]

Stop receiving logs as events.

interface {
  messageId: string;
  command: "stop_listening_logs";
}

Driver level commands

Get the config of the driver

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "driver.get_config";
}

Returns:

interface {
  config: {
    logConfig: {
      enabled: boolean;
      level: string | number; // schema versions >= 3 use string, <= 2 use number
      logToFile: boolean;
      filename: string;
      forceConsole: boolean;
    };
    statisticsEnabled: boolean;
  }
}

Update the logging configuration

[compatible with schema version: 4+]

NOTE: You must provide at least one key/value pair as part of config

interface {
  messageId: string;
  command: "driver.update_log_config";
  config: {
    enabled?: boolean;
    level?: string | number;
    logToFile?: boolean;
    filename?: string;
    forceConsole?: boolean;
  }
}

Get the logging configuration

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "driver.get_log_config";
}

Returns:

interface {
  config: {
    enabled: boolean;
    level: string | number; // schema versions >= 3 use string, <= 2 use number
    logToFile: boolean;
    filename: string;
    forceConsole: boolean;
  }
}

Enable data usage statistics collection

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "driver.enable_statistics";
  applicationName: string;
  applicationVersion: string;
}

Disable data usage statistics collection

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "driver.disable_statistics";
}

Get whether statistics are enabled

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "driver.is_statistics_enabled";
}

Returns:

interface {
  statisticsEnabled: boolean;
}

Set preferred scales

[compatible with schema version: 6+]

Set preferred sensor scales. The scales argument has the same type as preferences.scales in ZWaveOptions

interface {
  messageId: string;
  command: "driver.set_preferred_scales";
  scales: ZWaveOptions["preferences"]["scales"];
}

Check for config updates

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "driver.check_for_config_updates";
}

Install config update

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "driver.install_config_update";
}

Enable Error Reporting

[compatible with schema version: 16+]

interface {
  messageId: string;
  command: "driver.enable_error_reporting";
}

Peform a soft-reset (restart) on the controller

[compatible with schema version: 25+]

interface {
  messageId: string;
  command: "driver.soft_reset";
}

Attempt to perform a soft-reset (restart) on the controller

[compatible with schema version: 25+]

interface {
  messageId: string;
  command: "driver.try_soft_reset";
}

Shutdown

[compatible with schema version: 27+]

interface {
  messageId: string;
  command: "driver.shutdown";
}

Update Options

[compatible with schema version: 33+]

interface {
  messageId: string;
  command: "driver.update_options";
  options: EditableZWaveOptions;
}

Perform a hard reset on the controller

[compatible with schema version: 25+]

interface {
  messageId: string;
  command: "driver.hard_reset";
}

Shutdown the Z-Wave API on the controller

[compatible with schema version: 36+]

interface {
  messageId: string;
  command: "driver.shutdown";
}

Update driver options

[compatible with schema version: 36+]

interface {
  messageId: string;
  command: "driver.update_options";
  options: EditableZWaveOptions;
}

Send test frame to node

[compatible with schema version: 36+]

interface {
  messageId: string;
  command: "driver.send_test_frame";
  nodeId: number;
  powerlevel: Powerlevel;
}

Controller level commands

zwave-js-server supports all of the controller methods listed in the Z-Wave JS documentation. zwave-js-server uses snake casing for commands and prefixes every controller command with controller., so beginInclusion is called using the controller.begin_inclusion command.

NOTE: For the most part, controller commands have the same inputs as documented in the Z-Wave JS documentation. The exceptions are:

controller.begin_inclusion: in addition to the input types that are documented, this command will also accept the QR code string directly and will convert the string to a QRProvisioningInformation object automatically.

controller.provision_smart_start_node: in addition to the input types that are documented, this command will also accept the QR code string directly and will convert the string to a QRProvisioningInformation object automatically.

controller.backup_nvm_raw: This command will return a base64 encoded string for the NVM data.

controller.restore_nvm: The NVM input should be a base64 encoded string.

controller.firmware_update_otw: This command accepts two required parameters (file, a base64 representation of the file, and filename, the filename of the file) as well as an optional parameter (fileFormat, which provides the format of the file to the server so the driver does not have to guess the format)

Get controller state

[compatible with schema version: 14+]

interface {
  messageId: string;
  command: "controller.get_state";
}

Node level commands

Set value on a node

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "node.set_value";
  nodeId: number;
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
  value: any;
  options?: SetValueAPIOptions;
}

Refresh node info

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "node.refresh_info";
  nodeId: number;
  options?: RefreshInfoOptions;
}

Get defined Value IDs

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "node.get_defined_value_ids";
  nodeId: number;
}

Get value metadata

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "node.get_value_metadata";
  nodeId: number;
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
}

Get value

[compatible with schema version: 14+]

interface {
  messageId: string;
  command: "node.get_value";
  nodeId: number;
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
}

Get node state

[compatible with schema version: 14+]

interface {
  messageId: string;
  command: "node.get_state";
  nodeId: number;
}

Update Firmware

[compatible with schema version: 24+]

If firmwareFileFormat is not provided, the format will be guessed based on the filename and file payload.

interface {
  messageId: string;
  command: "node.begin_firmware_update";
  nodeId: number;
  updates: {
    filename: string;
    file: string; // use base64 encoding for the file
    fileFormat?: FileFormat;
  }[];
}

Abort Firmware Update

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "node.abort_firmware_update";
  nodeId: number;
}

Get Firmware Update Capabilities

[compatible with schema version: 0+]

interface {
  messageId: string;
  command: "node.get_firmware_update_capabilities";
  nodeId: number;
}

Get Firmware Update Capabilities Cached

[compatible with schema version: 21+]

interface {
  messageId: string;
  command: "node.get_firmware_update_capabilities_cached";
  nodeId: number;
}

Poll value

[compatible with schema version: 1+]

interface {
  messageId: string;
  command: "node.poll_value";
  nodeId: number;
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
}

Set raw configuration parameter value (Advanced)

[compatible with schema version: 1+]

interface {
  messageId: string;
  command: "node.set_raw_config_parameter_value";
  nodeId: number;
}

Refresh values

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "node.refresh_values";
  nodeId: number;
}

Interview command class

[compatible with schema version: 14+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.interview_cc";
  commandClass: CommandClasses;
}

Refresh command class values

[compatible with schema version: 4+]

interface {
  messageId: string;
  command: "node.refresh_cc_values";
  nodeId: number;
  commandClass: CommandClasses;
}

Ping

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "node.ping";
  nodeId: number;
}

Check if node has security class

[compatible with schema version: 8+]

interface {
  messageId: string;
  command: "node.has_security_class";
  nodeId: number;
  securityClass: SecurityClass;
}

Return the highest security class the node has

[compatible with schema version: 8+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.get_highest_security_class";
}

Test Powerlevel

[compatible with schema version: 13+]

This command emits events.

interface {
  messageId: string;
  nodeId: number;
  command: "node.test_powerlevel";
  testNodeId: number;
  powerlevel: Powerlevel;
  testFrameCount: number;
}

Check Lifeline Health

[compatible with schema version: 13+]

This command emits events.

interface {
  messageId: string;
  nodeId: number;
  command: "node.check_lifeline_health";
  rounds?: number;
}

Check Route Health

[compatible with schema version: 13+]

This command emits events.

interface {
  messageId: string;
  nodeId: number;
  command: "node.check_route_health";
  targetNodeId: number;
  rounds?: number;
}

Get endpoint count

[compatible with schema version: 14+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.get_endpoint_count";
}

Set name

[compatible with schema version: 14+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.set_name";
  updateCC?: boolean = true;
}

Set location

[compatible with schema version: 14+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.set_location";
  updateCC?: boolean = true;
}

Set keep awake

[compatible with schema version: 14+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.set_keep_awake";
}

Is Firmware Update In Progress

[compatible with schema version: 21+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.is_firmware_update_in_progress";
}

Wait for wakeup

[compatible with schema version: 18+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.wait_for_wakeup";
}

Interview

[compatible with schema version: 22+]

interface {
  messageId: string;
  nodeId: number;
  command: "node.interview";
}

Get value timestamp

[compatible with schema version: 27+]

interface {
  messageId: string;
  command: "node.get_value_timestamp";
  nodeId: number;
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
}

Manually Idle Notification CC Value

[compatible with schema version: 39+]

This can be called in one of two ways:

Method 1:

interface {
  messageId: string;
  command: "node.manually_idle_notification_value";
  valueId: ValueID;
}

Method 2:

interface {
  messageId: string;
  command: "node.manually_idle_notification_value";
  nodeId: number;
  notificationType: number;
  prevValue: number;
  endpointIndex?: number;
}

Set date and time

[compatible with schema version: 30+]

interface {
  messageId: string;
  command: "node.set_date_and_time";
  nodeId: number;
  date?: string; // use ISO 8601 date string format
}

Get date and time

[compatible with schema version: 31+]

interface {
  messageId: string;
  command: "node.get_date_and_time";
  nodeId: number;
}

Is Health Check In Progress

[compatible with schema version: 31+]

interface {
  messageId: string;
  command: "node.is_health_check_in_progress";
  nodeId: number;
}

Abort Health Check

[compatible with schema version: 31+]

interface {
  messageId: string;
  command: "node.abort_health_check";
  nodeId: number;
}

Set Default Volume

[compatible with schema version: 31+]

interface {
  messageId: string;
  command: "node.set_default_volume";
  nodeId: number;
  defaultVolume?: number;
}

Set Default Transition Duration

[compatible with schema version: 31+]

interface {
  messageId: string;
  command: "node.set_default_transition_duration";
  nodeId: number;
  defaultTransitionDuration?: string; // Will be converted to a Duration object
}

Has Device Config Changed

[compatible with schema version: 31+]

interface {
  messageId: string;
  command: "node.has_device_config_changed";
  nodeId: number;
}

Set Raw Config Parameter Value

[compatible with schema version: 33+]

interface {
  messageId: string;
  command: "node.set_raw_config_parameter_value";
  nodeId: number;
  parameter: number;
  bitMask?: number;
  value: ConfigValue;
  valueSize?: 1 | 2 | 4; // valueSize and valueFormat should be used together.
  valueFormat?: ConfigValueFormat;
}

Dump node debug data

[compatible with schema version: 36+]

interface {
  messageId: string;
  command: "node.create_dump";
}

Endpoint level commands

Invoke a Command Classes API method

[compatible with schema version: 7+]

You can find all of the CC API methods in the Z-Wave JS docs.

Example: Invoking UserCodeCC.set

Send the following JSON to the server to invoke UserCodeCC.set(1, UserIDStatus.Enabled, "1234"):

{
  "messageId": "invoke-usercode-cc-set",
  "command": "endpoint.invoke_cc_api",
  "nodeId": 2,
  "endpoint": 1,
  "commandClass": 99, // commandClass = CommandClasses["User Code"]
  "methodName": "set",
  "args": [
    1, // userId = 1
    1, // userIdStatus = UserIDStatus.Enabled
    "1234", // userCode = "1234"
  ],
}

interface {
  messageId: string;
  command: "endpoint.invoke_cc_api";
  nodeId: number;
  endpoint?: number;
  commandClass: CommandClasses;
  methodName: string;
  args: unknown[];
}

For Buffer type arguments, use the following JSON format to represent the argument:

{
  "type": "Buffer",
  "data": [], // array of numbers
}

Check whether a given Command Classes API is supported by the above method

[compatible with schema version: 7+]

interface {
  messageId: string;
  command: "endpoint.supports_cc_api";
  nodeId: number;
  endpoint?: number;
  commandClass: CommandClasses;
}

Check whether endpoint supports a given Command Class

[compatible with schema version: 23+]

interface {
  messageId: string;
  command: "endpoint.supports_cc";
  nodeId: number;
  endpoint?: number;
  commandClass: CommandClasses;
}

Check whether endpoint controls a given Command Class

[compatible with schema version: 23+]

interface {
  messageId: string;
  command: "endpoint.controls_cc";
  nodeId: number;
  endpoint?: number;
  commandClass: CommandClasses;
}

Check whether a given Command Class is secure

[compatible with schema version: 23+]

interface {
  messageId: string;
  command: "endpoint.is_cc_secure";
  nodeId: number;
  endpoint?: number;
  commandClass: CommandClasses;
}

Check version of a given Command Class

[compatible with schema version: 23+]

interface {
  messageId: string;
  command: "endpoint.get_cc_version";
  nodeId: number;
  endpoint?: number;
  commandClass: CommandClasses;
}

Get node from endpoint

[compatible with schema version: 40+]

interface {
  messageId: string;
  command: "endpoint.try_get_node";
  nodeId: number;
  endpoint?: number;
}

[compatible with schema version: 23+]

interface {
  messageId: string;
  command: "endpoint.get_node_unsafe";
  nodeId: number;
  endpoint?: number;
}

Get Raw Config Parameter Value

[compatible with schema version: 39+]

interface {
  messageId: string;
  command: "node.get_raw_config_parameter_value";
  nodeId: number;
  parameter: number;
  bitMask?: number;
}

interface {
  messageId: string;
  command: "endpoint.get_raw_config_parameter_value";
  nodeId: number;
  endpoint?: number;
  parameter: number;
  bitMask?: number;
}

Set Raw Config Parameter Value

[compatible with schema version: 33+]

interface {
  messageId: string;
  command: "node.set_raw_config_parameter_value";
  nodeId: number;
  parameter: number;
  bitMask?: number;
  value: ConfigValue;
  valueSize?: 1 | 2 | 4; // valueSize and valueFormat should be used together.
  valueFormat?: ConfigValueFormat;
}

interface {
  messageId: string;
  command: "endpoint.set_raw_config_parameter_value";
  nodeId: number;
  endpoint?: number;
  parameter: number;
  bitMask?: number;
  value: ConfigValue;
  valueSize?: 1 | 2 | 4; // valueSize and valueFormat should be used together.
  valueFormat?: ConfigValueFormat;
}

Multicasting

There are several commands available that can be multicast to multiple nodes simultaneously. If you would like to broadcast to all nodes, use the broadcast_node prefix for the following commands. If you would like to multicast to a subset of nodes, use the multicast_group prefix for the following commands, adding a nodeIDs list as an input parameter:

interface IncomingCommandMulticastGroupBase extends IncomingCommandBase {
  nodeIDs: number[];
}

As an example, here's how you would call the set_value command for a multicast group (note the extra nodeIDs input parameter):

interface {
  messageId: string;
  command: "multicast_group.set_value";
  nodeIDs: number[];
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
  value: any;
  options?: SetValueAPIOptions;
}

Set value

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "<prefix>.set_value";
  valueId: {
    commandClass: CommandClasses;
    endpoint?: number;
    property: string | number;
    propertyKey?: string | number;
  };
  value: any;
  options?: SetValueAPIOptions;
}

Get endpoint count

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "<prefix>.get_endpoint_count"
}

Check if endpoint supports a Command Class

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "<prefix>.supports_cc"
  index: number
  commandClass: CommandClasses
}

Get Command Class version on an endpoint

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "<prefix>.get_cc_version"
  index: number
  commandClass: CommandClasses
}

Invoke a Command Class specific API

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "<prefix>.invoke_cc_api"
  index?: number;  // Endpoint index
  commandClass: CommandClasses;
  methodName: string;
  args: unknown[];
}

Check if a Command Class is supported by invoke_cc_api

[compatible with schema version: 5+]

interface {
  messageId: string;
  command: "<prefix>.get_cc_version"
  index?: number;  // Endpoint index
  commandClass: CommandClasses;
}

Get defined value IDs

[compatible with schema version: 11+]

interface {
  messageId: string;
  command: "<prefix>.get_defined_value_ids"
}

Utility commands

zwave-js-server supports all of the utility methods listed in the Z-Wave JS documentation. zwave-js-server uses snake casing for commands and prefixes every controller command with utils., so parseQRCodeString is called using the utils.parse_qr_code_string command.

NOTE: While some string utility commands like num2hex, buffer2hex, etc. are made available in the server due to their availability within the driver, this functionality works best when implemented locally and should not be used over WebSocket for any practical purpose.

Config manager commands

zwave-js-server supports all of the config manager methods listed in the Z-Wave JS documentation. zwave-js-server uses snake casing for commands and prefixes every controller command with config_manager., so lookupDevice is called using the config_manager.lookup_device command.

Zniffer commands

zwave-js-server enables applications to interact with a Zniffer, and once started all events will be forwarded to clients. Note that the server deviates from the Z-Wave JS API slightly. See a description of the commands below.

Initialize Zniffer

Initialize the Zniffer. Security keys and log config will match what's configured for the driver, but all other zniffer options are configurable.