jcam/zwave-js-server

Z-Wave JS Server

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

Trying it out

Start server

ts-node cli/server.ts /dev/tty0

Opens server on ws://localhost: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.

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

Start client

Requires server to be running.

Default connects to ws://localhost:3000:

ts-node cli/client.ts

To specify different host:

ts-node cli/client.ts 192.168.1.100:6000

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

ts-node cli/client.ts --dump

API

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

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

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

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

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

Authentication

Z-Wave JS Server does not handle authentication and allows all connections to the websocket API. If you want to add authentication, add authentication middleware to your Express instance or run NGINX in front of Express instance.