Z-Wave JS Server

一个围绕 Z-Wave JS 的小型服务器封装，用于通过 WebSocket 访问它。

试用

以下说明仅用于开发。安装 NPM 包后，这些 CLI 将作为 zwave-server 和 zwave-client 提供。

启动服务器

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

在 ws://0.0.0.0:3000 上启动服务器。

您可以使用 --config 指定配置文件。这可以是一个 JSON 文件，或一个导出配置的 JS 文件。它需要遵循 Z-Wave JS 配置格式。

注意：除非在配置文件中指定，否则 emitValueUpdateAfterSetValue 配置选项将被设置为 true。这推荐用于多客户端设置以及多个应用程序共享访问同一驱动程序的情况，例如 zwavejs2mqtt

您可以使用 --port 为 websocket 服务器指定不同的监听端口，并使用 --host 指定要附加的接口，默认主机为 0.0.0.0，即所有接口。

如果您没有 USB 设备，可以添加 --mock-driver 以使用虚拟设备。

DNS-SD 在服务器中默认启用。如果您希望禁用它，请添加 --disable-dns-sd。

如果您想启用自动重连，请添加 --reconnect。

启动客户端

需要服务器正在运行。

默认连接到 ws://localhost:3000：

tsx src/bin/client.ts

要指定不同的主机：

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

要指定它每条消息输出在一行上，以便稍后可以重放：

tsx src/bin/client.ts --dump

您可以通过特定的节点 ID 过滤输出：

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

要指定除最新版本以外的模式版本（maxSchemaVersion）：

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

所有这些选项都可以组合使用。

API

当客户端连接时，服务器将发送版本信息。

interface {
  type: "version";
  driverVersion: string;
  serverVersion: string;
  homeId: number | undefined;
  minSchemaVersion: number;
  maxSchemaVersion: number;
}

要设置客户端支持的 schema 版本以及将添加到 web 请求中的可选 user agent，客户端应发送 initialize 命令。

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

要开始接收状态并获取事件，客户端需要发送 start_listening 命令。

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

服务器将响应当前状态并开始发送事件。

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

之后，客户端将收到 Z-Wave JS 内部发生的每次状态变更的通知。

事件键遵循 Z-Wave JS 所使用的名称/类型。

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

客户端命令

服务器级命令

开始监听事件

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

设置 API 模式版本

[兼容模式版本：0+]

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

开始监听日志事件

[兼容 schema 版本：31+]

开始以事件形式接收日志。有关事件的更多信息，请参阅 logging 事件文档]。如果包含 filter，则只有匹配 filter 的日志才会作为事件发送，其余日志将被跳过。

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

停止监听日志事件

[兼容 schema 版本：31+]

停止以事件形式接收日志。

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

驱动级命令

获取驱动的配置

[兼容 schema 版本：4+]

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

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

更新日志配置

[兼容模式版本：4+]

注意：您必须至少提供一个键值对作为 config 的一部分

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

获取日志配置

[兼容 schema 版本：4+]

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

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

启用数据使用统计收集

[兼容 schema 版本：4+]

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

禁用数据使用统计收集

[兼容 schema 版本：4+]

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

获取统计功能是否已启用

[兼容 schema 版本：4+]

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

interface {
  statisticsEnabled: boolean;
}

设置首选比例

[兼容模式版本：6+]

设置首选传感器比例。scales 参数与 ZWaveOptions 中的 preferences.scales 具有相同的类型

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

检查配置更新

[兼容 schema 版本：5+]

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

安装配置更新

[兼容 schema 版本：5+]

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

启用错误报告

[兼容 schema 版本：16+]

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

对控制器执行软复位（重启）

[兼容 schema 版本：25+]

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

尝试对控制器执行软重置（重启）

[兼容模式版本：25+]

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

对控制器执行硬重置

[兼容 schema 版本：25+]

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

在控制器上关闭 Z-Wave API

[兼容 schema 版本：36+]

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

更新驱动程序选项

[兼容模式版本：36+]

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

向节点发送测试帧

[兼容 schema 版本：36+]

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

固件更新 OTW (Over The Wire)

[兼容 schema 版本: 41+]

此命令使用通过线路获取的固件（例如，从互联网下载）执行控制器固件更新。固件更新可以通过以下两种方式提供：

选项 1: 提供原始固件文件（schema 41+）：

interface {
  messageId: string;
  command: "driver.firmware_update_otw";
  filename: string;
  file: string; // use base64 encoding for the file
  fileFormat?: FirmwareFileFormat;
}

选项 2：提供来自 Z-Wave JS 更新服务（schema 44+）的更新信息：

interface {
  messageId: string;
  command: "driver.firmware_update_otw";
  updateInfo: FirmwareUpdateInfo;
}

服务器将自动尝试从 ZIP 归档中提取固件。

如果选项 1 中未提供 fileFormat，则将根据文件名和文件内容猜测格式。

interface {
  result: OTWFirmwareUpdateResult;
}

OTW 固件更新正在进行中

[兼容 schema 版本：41+]

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

interface {
  progress: boolean;
}

软重置与重启

[兼容 schema 版本：47+]

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

进入 Bootloader

[兼容 schema 版本：47+]

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

离开 Bootloader

[兼容 schema 版本: 47+]

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

获取支持的 CC 版本

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "driver.get_supported_cc_version";
  cc: CommandClasses;
  nodeId: number;
  endpointIndex?: number;
}

获取安全 CC 版本

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "driver.get_safe_cc_version";
  cc: CommandClasses;
  nodeId: number;
  endpointIndex?: number;
}

更新用户代理

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "driver.update_user_agent";
  components: Record<string, string | null | undefined>;
}

启用频繁 RSSI 监控

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "driver.enable_frequent_rssi_monitoring";
  durationMs: number;
}

禁用频繁 RSSI 监控

[兼容 schema 版本：47+]

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

控制器级命令

zwave-js-server 支持 Z-Wave JS 文档] 中列出的所有控制器方法。zwave-js-server 对命令使用 snake casing，并为每个控制器命令添加 controller. 前缀，因此 beginInclusion 通过 controller.begin_inclusion 命令调用。

注意：在大多数情况下，controller 命令的输入与 Z-Wave JS 文档中记载的相同。例外情况如下：

回调到事件的转换： 多个 Z-Wave JS 控制器方法接受回调参数（例如 userCallbacks、onProgress）。由于无法通过 WebSocket 连接传递回调，服务器会自动提供回调，并向客户端发出事件。有关每个命令发出的事件的详细信息，请参阅“事件”部分。

controller.begin_inclusion、controller.replace_failed_node：userCallbacks 选项（用于 S2 安全引导）由服务器处理。服务器改为发出 grant security classes、validate dsk and enter pin 和 inclusion aborted 事件。此外，controller.begin_inclusion 还将直接接受 QR 码字符串，并自动将该字符串转换为 QRProvisioningInformation 对象。

controller.begin_joining_network：userCallbacks 选项由服务器处理。服务器改为发出 joining network show dsk 和 joining network done 事件。

controller.backup_nvm_raw：此命令将返回 NVM 数据的 base64 编码字符串。进度通过 nvm backup progress 事件报告。

controller.restore_nvm：NVM 输入应为 base64 编码字符串。进度通过 nvm convert progress 和 nvm restore progress 事件报告。

controller.restore_nvm_raw：NVM 输入应为 base64 编码字符串。与 restore_nvm 不同，此命令在恢复之前不会转换 NVM 数据。进度通过 nvm restore progress 事件报告。

controller.provision_smart_start_node：除了文档中记载的输入类型外，此命令还将直接接受 QR 码字符串，并自动将该字符串转换为 QRProvisioningInformation 对象。

controller.firmware_update_otw: 此命令接受两个必需参数（file，文件的 base64 表示，以及 filename，文件的文件名），以及一个可选参数（fileFormat，向服务器提供文件格式，以便驱动程序无需猜测格式）

controller.get_dsk: 以 base64 编码字符串的形式返回控制器的 DSK。

controller.external_nvm_read_buffer, controller.external_nvm_read_buffer_700, controller.external_nvm_read_buffer_ext: 这些命令在 buffer 字段中以 base64 编码字符串的形式返回 NVM 数据。

controller.external_nvm_write_buffer, controller.external_nvm_write_buffer_700, controller.external_nvm_write_buffer_ext: buffer 输入应为 base64 编码字符串。

controller.get_all_associations: 返回嵌套的 map 结构（nodeId -> endpoint -> groupId -> addresses），而非 Z-Wave JS API 使用的扁平结构。

controller.get_all_available_firmware_updates: 接受可选的 apiKey、includePrereleases 和 rfRegion 参数。

获取控制器状态

[兼容 schema 版本：14+]

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

节点级命令

在节点上设置值

[兼容 schema 版本：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;
}

刷新节点信息

[兼容 schema 版本: 0+]

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

获取已定义的 Value ID

[兼容 schema 版本：0+]

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

获取值元数据

[兼容模式版本：0+]

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

获取值

[兼容 schema 版本：14+]

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

获取节点状态

[兼容 schema 版本：14+]

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

获取受支持的 `notification` 事件

[兼容 schema 版本：41+]

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

开始固件更新

[兼容 schema 版本：0-23]

注意：对于 24 及更高版本的 schema，请使用 node.update_firmware。

如果未提供 firmwareFileFormat，格式将根据文件名和文件负载进行猜测。如果猜测失败，服务器将自动尝试从 ZIP 归档中提取固件。

interface {
  messageId: string;
  command: "node.begin_firmware_update";
  nodeId: number;
  firmwareFilename: string;
  firmwareFile: string; // use base64 encoding for the file
  firmwareFileFormat?: FirmwareFileFormat;
  target?: number;
}

更新固件

[兼容 schema 版本：24+]

此命令支持在单次操作中更新多个固件文件。

如果未提供 fileFormat，将根据文件名和文件内容猜测格式。如果猜测失败，服务器将自动尝试从 ZIP 归档中提取固件。

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

中止固件更新

[兼容模式版本：0+]

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

获取固件更新能力

[兼容 schema 版本：0+]

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

获取固件更新能力缓存

[兼容 schema 版本：21+]

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

Poll 值

[兼容 schema 版本：1+]

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

刷新值

[兼容模式版本：4+]

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

Interview 命令类

[兼容 schema 版本: 14+]

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

刷新命令类值

[兼容模式版本：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;
}

检查节点是否具有安全类

[兼容模式版本：8+]

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

返回节点拥有的最高安全级别

[兼容模式版本：8+]

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

测试 Powerlevel

[兼容 schema 版本：13+]

此命令会发出事件。

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

检查 Lifeline 健康状态

[兼容 schema 版本：13+]

此命令会发出事件。

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

检查路由健康

[兼容 schema 版本: 13+]

此命令会发出事件。

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

获取端点数量

[兼容 schema 版本：14+]

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

设置名称

[兼容 schema 版本：14+]

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

设置位置

[兼容 schema 版本：14+]

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

设置保持唤醒

[兼容 schema 版本：14+]

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

固件更新正在进行中

[兼容 schema 版本: 21+]

注意: 命令 node.get_firmware_update_progress 是该命令的别名，可以互换使用。

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

interface {
  progress: boolean;
}

等待唤醒

[兼容 schema 版本：18+]

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

面试

[兼容 schema 版本: 22+]

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

获取值时间戳

[兼容 schema 版本：27+]

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

手动空闲通知 CC 值

[兼容模式版本：39+]

这可以通过以下两种方式之一调用：

方法 1：

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

方法 2：

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

设置日期和时间

[兼容 schema 版本：30+]

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

获取日期和时间

[兼容模式版本：31+]

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

健康检查是否正在进行

[兼容模式版本：31+]

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

中止健康检查

[兼容 schema 版本：31+]

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

设置默认音量

[兼容 schema 版本：31+]

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

设置默认过渡时长

[兼容 schema 版本：31+]

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

设备配置是否已更改

[兼容模式版本：31+]

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

设置原始配置参数值

[兼容 schema 版本：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;
}

转储节点调试数据

[兼容 schema 版本：36+]

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

获取固件更新进度

[兼容模式版本：21+]

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

检查链接可靠性

[兼容 schema 版本：47+]

对节点执行扩展的链接可靠性检查。

在此命令运行期间，服务器会发出包含 { nodeId, progress } 的进度更新 check link reliability progress 事件。

interface {
  messageId: string;
  command: "node.check_link_reliability";
  nodeId: number;
  mode: "rssi" | "latency" | "routeChanges";
  interval: number;
  rounds?: number;
}

链接可靠性检查是否正在进行

[兼容 schema 版本：47+]

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

中止链接可靠性检查

[兼容 schema 版本：47+]

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

端点级命令

调用 Command Classes API 方法

[兼容 schema 版本：7+]

您可以在 Z-Wave JS 文档中找到所有 CC API 方法。

示例：调用 UserCodeCC.set

向服务器发送以下 JSON 以调用 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[];
}

对于 Buffer 类型的参数，请使用以下 JSON 格式来表示该参数：

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

统一凭证管理 API（用户/凭证）

[兼容模式版本：48+]

这些命令直接通过 endpoint.access_control.* 命名空间暴露 Z-Wave JS 的统一凭证管理 API。Z-Wave JS 会在适用时自动处理 User Credential CC 与 User Code CC 的回退。

在使用其他任何命令之前，应用程序应检查该端点是否暴露了统一访问控制 API：

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

响应中包含 supported: boolean。

支持的命令：

endpoint.access_control.is_supported
endpoint.access_control.get_user_capabilities_cached
endpoint.access_control.get_credential_capabilities_cached
endpoint.access_control.get_user
endpoint.access_control.get_user_cached
endpoint.access_control.get_users
endpoint.access_control.get_users_cached
endpoint.access_control.set_user
endpoint.access_control.delete_user
endpoint.access_control.delete_all_users
endpoint.access_control.get_credential
endpoint.access_control.get_credential_cached
endpoint.access_control.get_credentials
endpoint.access_control.get_credentials_cached
endpoint.access_control.get_credentials_by_type
endpoint.access_control.get_credentials_by_type_cached
endpoint.access_control.get_all_credentials
endpoint.access_control.get_all_credentials_cached
endpoint.access_control.assign_credential
endpoint.access_control.set_credential
endpoint.access_control.delete_credential
endpoint.access_control.start_credential_learn
endpoint.access_control.cancel_credential_learn
endpoint.access_control.get_admin_code
endpoint.access_control.set_admin_code

变更命令返回一个 result 字段，其中包含一个枚举值：

set_user, delete_user, delete_all_users → SetUserResult
set_credential, delete_credential → SetCredentialResult
assign_credential → AssignCredentialResult

所有命令使用相同的基础参数：

interface {
  messageId: string;
  command: string; // one of the commands above
  nodeId: number;
  endpoint?: number;
}

示例：设置凭据

interface {
  messageId: string;
  command: "endpoint.access_control.set_credential";
  nodeId: number;
  endpoint?: number;
  userId: number;
  credentialType: number;
  credentialSlot: number;
  data: string | { type: "Buffer"; data: number[] };
}

示例：创建或修改用户

interface {
  messageId: string;
  command: "endpoint.access_control.set_user";
  nodeId: number;
  endpoint?: number;
  userId: number;
  options: {
    active?: boolean;
    userType?: number;
    userName?: string;
    credentialRule?: number;
    expiringTimeoutMinutes?: number;
  };
}

示例：将凭据重新分配给其他用户

interface {
  messageId: string;
  command: "endpoint.access_control.assign_credential";
  nodeId: number;
  endpoint?: number;
  credentialType: number;
  credentialSlot: number;
  destinationUserId: number;
}

检查给定的 Command Classes API 是否受上述方法支持

[兼容 schema 版本：7+]

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

检查端点是否支持给定的 Command Class

[兼容 schema 版本：23+]

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

检查端点是否控制给定的 Command Class

[兼容 schema 版本：23+]

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

检查给定的 Command Class 是否安全

[兼容 schema 版本：23+]

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

检查给定 Command Class 的版本

[兼容 schema 版本：23+]

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

从端点获取节点

[兼容 schema 版本：40+]

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

[兼容 schema 版本：23+]

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

获取原始配置参数值

[兼容 schema 版本：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;
}

设置原始配置参数值

[兼容 schema 版本: 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;
}

获取命令类

[兼容 schema 版本：47+]

获取此端点支持的所有命令类。

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

May Support Basic CC

[compatible with schema version: 47+]

检查该端点是否可能支持 Basic CC。

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

CC 是否通过配置被移除

[兼容 schema 版本: 47+]

检查命令类是否已通过设备配置从端点中移除。

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

多播

有多个可用的命令，可以同时多播到多个节点。如果您希望广播到所有节点，请使用以下命令的 broadcast_node 前缀。如果您希望多播到节点子集，请使用以下命令的 multicast_group 前缀，并将 nodeIDs 列表作为输入参数添加。

注意：对于 broadcast_node 命令，您可以传递一个 longRange 布尔标志，以广播到 Long Range 节点，而不是经典 Z-Wave 节点。

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

例如，以下是为多播组调用 set_value 命令的方式（注意额外的 nodeIDs 输入参数）：

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;
}

设置值

[兼容 schema 版本：5+]

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

获取端点数量

[兼容 schema 版本：5+]

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

检查端点是否支持命令类

[兼容模式版本：5+]

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

获取端点上的 Command Class 版本

[兼容 schema 版本：5+]

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

调用命令类特定 API

[兼容 schema 版本：5+]

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

检查命令类是否受 invoke_cc_api 支持

[兼容 schema 版本：5+]

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

获取已定义的值 ID

[兼容 schema 版本：11+]

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

实用命令

zwave-js-server 支持 Z-Wave JS 文档] 中列出的所有实用方法。zwave-js-server 对命令使用 snake casing，并为每个控制器命令添加 utils. 前缀，因此 parseQRCodeString 通过 utils.parse_qr_code_string 命令调用。

注意：虽然某些字符串实用命令（如 num2hex、buffer2hex 等）因在驱动程序中可用而在服务器中提供，但此功能在本地实现时效果最佳，不应出于任何实际目的通过 WebSocket 使用。

配置管理器命令

zwave-js-server 支持 Z-Wave JS 文档] 中列出的所有配置管理器方法。zwave-js-server 对命令使用 snake casing，并为每个控制器命令添加 config_manager. 前缀，因此 lookupDevice 通过 config_manager.lookup_device 命令调用。

Zniffer 命令

zwave-js-server 使应用程序能够与 Zniffer 交互，一旦启动，所有事件都将转发给客户端。请注意，服务器与 Z-Wave JS API 略有不同。请参阅以下命令说明。

初始化 Zniffer

初始化 Zniffer。安全密钥和日志配置将与驱动程序中配置的内容匹配，但所有其他 zniffer 选项均可配置。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.init";
  devicePath: "/path/to/device";
  options: Omit<ZnifferOptions, "logConfig" | "securityKeys" | "securityKeysLongRange">;
}

启动 Zniffer

启动 Zniffer。必须先初始化 Zniffer。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.start";
}

停止 Zniffer

停止 Zniffer 实例。

[兼容 schema 版本: 38+]

interface {
  messageId: string;
  command: "zniffer.stop";
}

销毁 Zniffer

销毁 Zniffer 实例。

[兼容 schema 版本: 38+]

interface {
  messageId: string;
  command: "zniffer.destroy";
}

获取捕获的帧

返回捕获帧的列表。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.captured_frames";
}

清除已捕获的帧

清除所有已捕获的帧。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.clear_captured_frames";
}

以 ZLF 缓冲区获取捕获的帧

以 JSON 字符串化的缓冲区形式返回 ZLF 文件格式的捕获帧。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.get_capture_as_zlf_buffer";
}

获取支持的频率

获取支持的频率列表及其名称。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.supported_frequencies";
}

获取当前频率

获取当前频率。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.current_frequency";
}

设置频率

设置 Zniffer 频率。

[兼容 schema 版本：38+]

interface {
  messageId: string;
  command: "zniffer.set_frequency";
  frequency: number;
}

获取长距离区域

获取支持长距离的区域列表。

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "zniffer.get_lr_regions";
}

获取当前 Long Range 通道配置

获取当前已配置的 Long Range 通道配置。

[兼容 schema 版本: 47+]

interface {
  messageId: string;
  command: "zniffer.get_current_lr_channel_config";
}

获取受支持的 Long Range 信道配置

获取受支持的 Long Range 信道配置映射。

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "zniffer.get_supported_lr_channel_configs";
}

设置长距离信道配置

设置长距离信道配置（仅限 800 系列）。

[兼容 schema 版本：47+]

interface {
  messageId: string;
  command: "zniffer.set_lr_channel_config";
  channelConfig: number;
}

从缓冲区加载捕获

从 base64 编码的缓冲区加载捕获的帧。

[兼容 schema 版本: 47+]

interface {
  messageId: string;
  command: "zniffer.load_capture_from_buffer";
  data: string; // base64 encoded .zlf data
}

事件

`zwave-js` 事件

所有如文档所述 zwave-js 事件都会转发给已发送 start_listening 命令的客户端。

interface {
  type: "event";
  event: {
    source: "driver" | "controller" | "node" | "zniffer";
    event: string;
    ... // Additional parameters dependent on the event, see zwave-js docs for more details
  }
}

`zwave-js-server` 节点事件

`test powerlevel progress`

此事件在发出 node.test_powerlevel 命令后发送，并包含来自驱动程序的结果。有关此命令的更多信息，请参阅 zwave-js 关于此命令的文档]。

interface {
  type: "event";
  event: {
    source: "node";
    event: "test powerlevel progress";
    nodeId: number;
    acknowledged: number;
    total: number;
  }
}

`check lifeline health progress`

此事件在发出 node.check_lifeline_health 命令后发送，并包含来自驱动程序的结果。有关此命令的更多信息，请参阅 zwave-js 关于此命令的文档]。

interface {
  type: "event";
  event: {
    source: "node";
    event: "check lifeline health progress";
    nodeId: number;
    round: number;
    totalRounds: number;
    lastRating: number;
  }
}

`check route health progress`

此事件在发出 node.check_route_health 命令后发送，并包含来自驱动程序的结果。有关此命令的更多信息，请参阅 zwave-js 关于此命令的文档]。

interface {
  type: "event";
  event: {
    source: "node";
    event: "check route health progress";
    nodeId: number;
    rounds: number;
    totalRounds: number;
    lastRating: number;
  }
}

`check link reliability progress`

[兼容 schema 版本：47+]

此事件在发出 node.check_link_reliability 命令后发送，并包含来自驱动程序的进度更新。有关此命令的更多信息，请参阅 zwave-js 文档]。

interface {
  type: "event";
  event: {
    source: "node";
    event: "check link reliability progress";
    nodeId: number;
    progress: LinkReliabilityCheckResult;
  }
}

访问控制事件

[兼容模式版本：48+]

来自 zwave-js 的统一访问控制事件将附带端点上下文进行转发：

user added
user modified
user deleted
credential added
credential modified
credential deleted
credential learn progress
credential learn completed

interface {
  type: "event";
  event: {
    source: "node";
    event: string;
    nodeId: number;
    endpointIndex: number;
    args: Record<string, unknown>;
  }
}

args 的示例：

user added / user modified: { userId, active, userType, userName?, credentialRule?, expiringTimeoutMinutes? }
user deleted: { userId }
credential added / credential modified: { userId, credentialType, credentialSlot, data? }
credential deleted: { userId, credentialType, credentialSlot }
credential learn progress: { userId, credentialType, credentialSlot, stepsRemaining, status }
credential learn completed: { userId, credentialType, credentialSlot, status, success }

`zwave-js-server` 驱动程序事件

`driver ready`

此事件在驱动程序指示其已准备就绪时发送，例如在硬重置之后。

interface {
  type: "event";
  event: {
    source: "driver";
    event: "driver ready";
  }
}

`all nodes ready`

[compatible with schema version: 47+]

当所有节点均已完成访谈并准备就绪时，将发送此事件。

interface {
  type: "event";
  event: {
    source: "driver";
    event: "all nodes ready";
  }
}

`error`

[compatible with schema version: 47+]

当发生驱动程序错误时，会发送此事件。

interface {
  type: "event";
  event: {
    source: "driver";
    event: "error";
    error: string;
  }
}

`bootloader ready`

[compatible with schema version: 47+]

当控制器进入 bootloader 模式时，会发送此事件。

interface {
  type: "event";
  event: {
    source: "driver";
    event: "bootloader ready";
  }
}

`log config updated`

每当客户端使用更新后的日志配置发出 driver.update_log_config 命令时，就会发送此事件。

interface {
  type: "event";
  event: {
    source: "driver";
    event: "log config updated";
    config: Partial<LogConfig>; // Includes everything but `transports`
  }
}

`logging`

每当 zwave-js 记录一条语句时，都会发送此事件。只有当客户端已发出 driver.start_listening_logs 命令时，才会收到这些事件。

interface {
  type: "event";
  event: {
    source: "driver";
    event: "logging";
    formattedMessage: string;
    direction: string;
    primaryTags?: string;
    secondaryTags?: string;
    secondaryTagPadding?: number;
    multiline?: boolean;
    timestamp?: string;
    label?: string;
    message: string | string[];
  }
}

`zwave-js-server` 控制器事件

`grant security classes`

此事件作为节点包含流程的一部分发送（包括替换故障节点时）。该事件向客户端指示用户需要选择授予该节点哪些安全类。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "grant security classes";
    requested: InclusionGrant;
  }
}

`validate dsk and enter pin`

此事件作为节点包含流程的一部分发送（包括替换故障节点时）。该事件向客户端指示用户需要确认所提供的 DSK 有效，并输入设备上的 PIN。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "validate dsk and enter pin";
    dsk: string;
  }
}

`inclusion aborted`

此事件作为节点包含流程的一部分发送（包括替换故障节点时）。该事件向客户端指示，控制器已中止安全引导流程（这将在包含操作已经成功之后发生）。日志中可能包含有关中止此安全引导流程原因的更多详细信息。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "inclusion aborted";
  }
}

`nvm backup progress`

当客户端向服务器发出 controller.backup_nvm_raw 命令且备份正在进行时，此事件会在 NVM 备份过程的进度更新时发送。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "nvm backup progress";
    bytesRead: number;
    total: number;
  }
}

`nvm convert progress`

当事件在 NVM 转换过程中发送进度更新时，即客户端向服务器发出 controller.restore_nvm 命令，且传入的 NVM 文件正在被转换为正确格式时。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "nvm convert progress";
    bytesRead: number;
    total: number;
  }
}

`nvm restore progress`

当事务由客户端向服务器发出 controller.restore_nvm 或 controller.restore_nvm_raw 命令，且 NVM 数据正在恢复至控制器时，此事件会在 NVM 恢复过程的进度更新时发送。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "nvm restore progress";
    bytesWritten: number;
    total: number;
  }
}

`network found`

[compatible with schema version: 47+]

在加入过程（learn mode）中发现新网络时，会发送此事件。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "network found";
    homeId: number;
    ownNodeId: number;
  }
}

`network joined`

[compatible with schema version: 47+]

当控制器成功加入网络时，会发送此事件。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "network joined";
  }
}

`network left`

[compatible with schema version: 47+]

当控制器离开当前网络时，会发送此事件。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "network left";
  }
}

`joining network show dsk`

[compatible with schema version: 47+]

此事件在 controller.begin_joining_network 过程中发送，当 DSK 需要显示给用户进行验证时。此事件取代了 Z-Wave JS API 中的 showDSK 回调。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "joining network show dsk";
    dsk: string;
  }
}

`joining network done`

[compatible with schema version: 47+]

当事件在 controller.begin_joining_network 进程完成其面向用户的步骤时发送。此事件取代了 Z-Wave JS API 中的 done 回调。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "joining network done";
  }
}

`joining network failed`

[compatible with schema version: 47+]

此事件在加入网络失败时发送。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "joining network failed";
  }
}

`leaving network failed`

[compatible with schema version: 47+]

当离开网络失败时，会发送此事件。

interface {
  type: "event";
  event: {
    source: "controller";
    event: "leaving network failed";
  }
}

模式版本

为了在不同服务器和客户端版本之间保持兼容性，我们引入了一个（基础的）API 模式版本。

客户端连接 --> 服务器返回版本信息，包括其可处理的模式版本：

{
  "type": "version",
  "driverVersion": "6.5.0",
  "serverVersion": "1.0.0",
  "homeId": 3967882672,
  "minSchemaVersion": 0,
  "maxSchemaVersion": 1
}

客户端根据支持的 schema 版本决定如何处理。例如，如果支持的服务器 schema 过旧，则断开连接，或者直接处理所支持的 schema。例如，大多数/所有基本命令都能正常工作，但相对较新的命令则不行，客户端决定不处理升级后 schema 中的内容。
客户端需要告知服务器它想要使用的 schema。 这通过 "set_api_schema" 命令完成：
```
{
  "command": "set_api_schema",
  "messageId": 1,
  "schemaVersion": 1
}
```

从这一刻起，服务器知道如何对待来自/发往此客户端的命令。服务器可以处理具有不同 schema 版本的多个客户端。

如果省略 set_api_schema 命令，服务器默认将使用其支持的最低 schema（目前为 0）。

如果客户端发送的 schema 版本超出范围，这将向客户端产生错误，并在服务器日志中记录：

{
  "command": "set_api_schema",
  "messageId": 1,
  "schemaVersion": 3
}
{"type":"result","success":false,"messageId":1,"errorCode":"schema_incompatible"}

当我们在 api 中进行破坏性更改时，我们会提升 schema 版本。在添加新命令/功能时，我们也会提升 api schema，并在代码注释和文档中注明该功能兼容的 schema 版本。

Errors

如果命令导致错误，将返回以下响应：

{
  "type": "result",
  "success": false,
  "messageId": 1,
  "errorCode": "schema_incompatible"
}

以下错误代码存在：

code	description
unknown_command	未知命令
node_not_found	未找到节点
endpoint_not_found	未找到端点
virtual_endpoint_not_found	未找到虚拟端点
schema_incompatible	不兼容的 Schema
zwave_error	来自 Z-Wave JS 的错误
inclusion_phase_not_in_progress	包含阶段未在进行中
inclusion_already_in_progress	包含已在进行中
invalid_params_passed_to_command	传递给命令的参数无效
no_longer_supported	不再支持该功能
unknown_error	未知异常

在 zwave_error 的情况下，将添加额外的键 zwaveErrorCode 和 zwaveErrorMessage。

{
  "type": "result",
  "success": false,
  "messageId": 1,
  "errorCode": "zwave_error",
  "zwaveErrorCode": 18,
  "zwaveErrorMessage": "The message cannot be sent because node 61 is dead"
}

身份验证

Z-Wave JS Server 不处理身份验证，并允许所有连接到 websocket API。如果您想添加身份验证，请在您的 Express 实例中添加身份验证中间件，或在 Express 实例前面运行 NGINX。

Z-Wave JS Server

试用

启动服务器

启动客户端

API

客户端命令

服务器级命令

开始监听事件

设置 API 模式版本

开始监听日志事件

停止监听日志事件

驱动级命令

获取驱动的配置

控制器级命令

获取控制器状态

节点级命令

获取节点状态

端点级命令

统一凭证管理 API（用户/凭证）

多播

实用命令

配置管理器命令

Zniffer 命令

初始化 Zniffer

启动 Zniffer

停止 Zniffer

销毁 Zniffer

获取捕获的帧

清除已捕获的帧

以 ZLF 缓冲区获取捕获的帧

获取支持的频率

获取当前频率

设置频率

获取长距离区域

获取当前 Long Range 通道配置

获取受支持的 Long Range 信道配置

设置长距离信道配置

事件

zwave-js 事件

zwave-js-server 节点事件

test powerlevel progress

check lifeline health progress

check route health progress

check link reliability progress

访问控制事件

zwave-js-server 驱动程序事件

driver ready

all nodes ready

error

bootloader ready

log config updated

logging

zwave-js-server 控制器事件

grant security classes

validate dsk and enter pin

inclusion aborted

nvm backup progress

nvm convert progress

nvm restore progress

network found

network joined

network left

`zwave-js` 事件

`zwave-js-server` 节点事件

`test powerlevel progress`

`check lifeline health progress`

`check route health progress`

`check link reliability progress`

`zwave-js-server` 驱动程序事件

`driver ready`

`all nodes ready`

`error`

`bootloader ready`

`log config updated`

`logging`

`zwave-js-server` 控制器事件

`grant security classes`

`validate dsk and enter pin`

`inclusion aborted`

`nvm backup progress`

`nvm convert progress`

`nvm restore progress`

`network found`

`network joined`

`network left`