Z-Wave

Z-Wave integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 允许您通过 Z-Wave JS 驱动程序从 Home Assistant 控制 Z-Wave 网络。

设备兼容性

您不需要专门为 Home Assistant 中的 Z-Wave 集成设计的 Z-Wave 控制器。Home Assistant 中的 Z-Wave 集成可以与其他制造商的其他 Z-Wave 认证设备的任何 Z-Wave 网络一起操作。网络中的所有主电源节点将充当中继器，无论供应商如何，以提高网络的可靠性。

入门

本节向您展示如何设置 Z-Wave JS 服务器以及如何将您的第一个 Z-Wave 设备添加到 Home Assistant。它还向您介绍了一些基本术语。

Z-Wave 术语和 Home Assistant

在整个文档中，使用了 Home Assistant 术语。对于某些概念，术语与 Z-Wave 文档中使用的术语不对应。下表提供了其中一些术语的等价物。

经典包含与 SmartStart

Home Assistant 支持 经典包含 和 SmartStart。经典包含 意味着您将集线器和要包含的设备设置为相应的模式。替代方法是 SmartStart，其中集线器不断监听来自希望加入网络的设备的包含请求。

相关主题

有关更多 Z-Wave 术语定义，请参阅 术语部分。

先决条件

要运行 Z-Wave 网络，您需要以下元素：

• 一个 支持的 Z-Wave 控制器。第一次使用？有关购买建议，请参阅 此处。
• 一个正在运行的 Z-Wave JS 服务器。
• 在 Home Assistant 中安装的 Z-Wave 集成。

设置 Z-Wave JS 服务器

如果您正在运行 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 或 Home Assistant SupervisedHome Assistant Supervised 是完整的 Home Assistant 生态系统，没有 Home Assistant 操作系统。 [Learn more]，最简单的入门方法是使用 Home Assistant 中内置的 Z-Wave JS 插件。

有关设置 Z-Wave 服务器的其他方法，请参阅 高级安装说明。

请按照以下步骤操作：

1. 打开 Home Assistant 用户界面。
2. 将 Z-Wave 加密狗插入运行 Home Assistant 的设备。
   • 您的加密狗很可能会自动识别。在用户界面上，系统会询问您是否要使用 Z-Wave JS 插件设置此设备。选择 提交。
   • 如果未识别到您的加密狗，请按照以下步骤操作：

3. 等待安装完成。
4. 系统会提示您输入网络安全密钥。
   • 如果您是第一次使用 Z-Wave，请将所有字段留空并选择 提交。系统将为您生成网络安全密钥。
   • 如果此 Z-Wave 加密狗已与安全设备配对，则需要将以前使用的网络密钥作为 S0 网络密钥输入。S2 安全密钥将自动为您生成。
   • 确保将这些密钥的备份保存在安全的地方，以防需要将 Z-Wave 加密狗移动到其他设备。将它们复制并粘贴到安全的地方。
5. 等待 Z-Wave JS 插件启动。
6. 安装完成后，将显示 Z-Wave 控制器的 设备信息。
   • 您已成功安装 Z-Wave 集成和 Z-Wave JS 插件。
   • 您现在可以将设备添加到 Z-Wave 网络。

将新设备添加到 Z-Wave 网络

1. 在 Home Assistant 中，转到 设置 > 设备和服务。
2. 选择 Z-Wave 集成。然后选择 配置。
3. 选择 添加设备。
   • Z-Wave 控制器现在处于包含模式。
4. 检查您的设备是否支持 SmartStart：
   • 在包装上检查 SmartStart 标签。
   • 找到二维码。它可以在包装上或设备本身上。
5. 根据您的设备是否支持 SmartStart，按照选项 1 或 2 中的步骤操作：
   • 选项 1：您的设备支持 SmartStart：
     • 选择 扫描二维码 并扫描设备上的二维码。
     • 如果扫描不起作用（例如由于缺少 HTTPS），请从其他 QR 阅读器中粘贴 QR 代码内容并选择 提交。
     • 打开设备。如果它已经打开，您可能需要重新启动它。
   • 选项 2：您的设备不支持 SmartStart：
     • 将设备设置为包含模式。请参阅设备手册以了解如何操作。
     • 如果您的设备使用 S2 安全性包含，系统可能会提示您输入设备提供的 PIN 码。通常，此 PIN 与文档一起提供，并且还打印在设备本身上。有关安全包含的更多信息，请参阅 此部分。
6. 用户界面应确认设备已添加。稍等片刻（几秒到几分钟），实体也应创建。
7. 故障排除：如果控制器未能添加/找到您的设备，请取消包含过程。
   • 在某些情况下，即使设备尚未添加到此 Z-Wave 网络中，首先 删除 设备（排除）可能会有所帮助。
   • 另一种方法是恢复设备的出厂设置。请参阅设备手册以了解如何操作。

重要：

1. 不要移动您的 Z-Wave 加密狗以包含设备。 移动控制器不再必要，并会导致路由中断。
2. 不要从 Z-Wave 加密狗本身启动设备包含。 这不再受支持。

从 Z-Wave 网络中删除设备

1. 在 Home Assistant 中，转到 设置 > 设备和服务。
2. 选择 Z-Wave 集成。然后，选择 配置。
3. 选择 删除设备，然后选择 开始排除。
   • Z-Wave 控制器现在处于排除模式。
4. 将要删除的设备置于排除模式。请参阅其手册以了解如何操作。
5. 用户界面应确认设备已删除，设备和实体将从 Home Assistant 中删除。

特殊 Z-Wave 实体

Z-Wave 集成提供了几个特殊实体，其中一些适用于每个 Z-Wave 设备，而其中一些则根据设备的不同而有所不同。

每个 Z-Wave 设备可用的实体

1. 节点状态 传感器：此传感器显示给定 Z-Wave 设备的节点状态。默认情况下禁用传感器。可用的节点状态在 Z-Wave JS 文档 中进行了说明。它们可以用于状态更改自动化。例如，当设备死亡时对其进行 ping，或在设备唤醒时刷新值。
2. Ping 按钮：可以按下此按钮以 ping 设备。它是 zwave_js.ping 操作的替代方法。
3. 控制器/节点统计 传感器：Z-Wave JS 收集有关 节点 和 控制器 之间通信的统计信息。这些统计信息可用于排除环境中的 RF 问题。这些统计信息在网络配置和设备信息面板中可用。但它们也作为传感器提供，默认情况下禁用。

条件实体

1. 手动空闲通知 按钮：设备上具有空闲状态的任何通知命令类 (CC) 值将获得相应的按钮实体。当通知不会自动清除时，可以使用此按钮实体手动将通知置于空闲状态。设备可以有多个通知 CC 值。例如，一个用于检测烟雾，一个用于检测一氧化碳。

使用高级功能（仅限 UI）

虽然集成旨在通过现有的 Home Assistant 构造（实体、状态、自动化、操作等）提供尽可能多的功能，但有些功能仅通过 UI 可用。

所有这些功能都可以在 Z-Wave 集成配置面板或 Z-Wave 设备的设备面板中访问。

集成配置面板

可以从集成配置面板访问以下功能：

• 添加设备：允许您预先配置 SmartStart 设备或启动包含过程以将新设备添加到您的网络。
• 删除设备：启动排除过程以从网络中删除设备。
• 重建网络路由：强制您的网络重新发现从每个设备到控制器的路由。这在设备或控制器移动到新位置时很有用，或者如果您的网络存在重大问题，但它也会生成大量网络流量，应谨慎使用。
• 控制器统计：提供有关控制器与其他设备之间通信的统计信息，允许您排除网络的 RF 质量问题。
• 第三方数据选择加入/退出：允许您选择加入或退出 Z-Wave JS 项目收集的遥测数据，以帮助做出开发决策、影响制造商等。默认情况下禁用此遥测，必须选择加入才能激活。

集成菜单

某些功能可以从集成本身的菜单中访问。由于它们不是特定于 Z-Wave 的，因此在此不详细描述。

• 下载诊断：导出描述此集成注册的所有设备实体的 JSON 文件。

设备面板

控制器

可以从 Z-Wave 控制器的设备面板访问以下功能：

• 恢复出厂设置：使用此操作时要非常小心！一旦启动，您的控制器将恢复出厂设置，它将忘记所有配对的设备，它将建立一个新的网络 ID，防止任何恢复旧网络的可能性，并且所有 Z-Wave 设备将从 Home Assistant 中删除。如果在重置控制器时仍有设备与其配对，则必须先进行排除过程，然后才能重新配对。

显示 Z-Wave 控制器设备面板的屏幕截图。

网络设备

可以从网络中任何 Z-Wave 设备的设备面板（控制器除外）访问以下功能：

• 配置：提供一种简便的方法来查找和更新设备的配置参数。虽然有一个现有的操作用于设置配置参数值，但此 UI 有时可能更快地用于一次性更改。
• 重新采访：强制设备再次进行采访过程，以便 Z-Wave-JS 可以发现其所有功能。如果您没有看到设备的所有预期实体，这可能会有所帮助。
• 重建路由：强制设备重新发现其到控制器的最佳路由。如果您认为设备存在意外延迟或 RF 问题，请使用此功能。在此过程中，您的设备可能响应较慢。
• 删除失败：强制控制器从控制器中删除设备。当设备已失败且无法通过正常排除过程时，可以使用此功能。
• 统计：提供有关此设备与控制器之间通信的统计信息，允许您排除设备的 RF 问题。
• 更新：使用手动上传的固件文件更新设备的固件。只有某些设备支持此功能（具有固件更新元数据命令类的控制器和设备）。
• 下载诊断：导出描述此特定设备实体的 JSON 文件。

操作

操作 zwave_js.set_config_parameter

此操作将更新配置参数。要在单个调用中更新多个部分参数，请使用 zwave_js.bulk_set_partial_config_parameters 操作。

设置单个参数值的示例

让我们使用 此设备 的参数 31 作为示例，展示如何设置 LED 1 Blink Status (bottom) 部分参数的不同方法。请注意，在使用相同键的不同值的地方，不同的值在示例中是可以互换的。例如，我们可以在所有示例中互换使用 1 或 Blink 作为 value。

示例 1：

action: zwave_js.set_config_parameter
target:
  entity_id: switch.fan
data:
  parameter: 31
  bitmask: 0x01
  value: 1

示例 2：

action: zwave_js.set_config_parameter
target:
  entity_id: switch.fan
data:
  parameter: 31
  bitmask: 1
  value: "Blink"

示例 3：

action: zwave_js.set_config_parameter
target:
  entity_id: switch.fan
data:
  entity_id: switch.fan
  parameter: "LED 1 Blink Status (bottom)"
  value: "Blink"

操作 zwave_js.bulk_set_partial_config_parameters

此操作将批量设置多个部分配置参数。请注意，正确使用此操作需要对 Z-Wave 有深入了解。

批量设置部分参数值的示例

让我们使用 此设备 的参数 21 作为示例，展示如何批量设置部分参数。在这种情况下，我们希望将 0xff 设置为 127，将 0x7f00 设置为 10，将 0x8000 设置为 1（或原始值 4735）。

示例 1：

action: zwave_js.bulk_set_partial_config_parameters
target:
  entity_id: switch.fan
data:
  parameter: 21
  value: 4735

示例 2：

action: zwave_js.bulk_set_partial_config_parameters
target:
  entity_id: switch.fan
data:
  parameter: 21
  value:
    0xff: 127
    0x7f00: 10
    0x8000: 1

示例 3：

action: zwave_js.bulk_set_partial_config_parameters
target:
  entity_id: switch.fan
data:
  parameter: 21
  value:
    255: 127
    32512: 10
    32768: 1

示例 4：

action: zwave_js.bulk_set_partial_config_parameters
target:
  entity_id: switch.fan
data:
  parameter: 21
  value:
    255: 127
    32512: 10
    32768: "Fine"

示例 5：

action: zwave_js.bulk_set_partial_config_parameters
target:
  entity_id: switch.fan
data:
  parameter: 21
  value:
    "Quick Strip Effect: Hue Color Wheel / Color Temp": 127
    "Quick Strip Effect Intensity": 10
    "Quick Strip Effect Intensity Scale": "Fine"

操作 zwave_js.refresh_value

此操作将刷新实体的值。此操作将在您的 Z-Wave 网络上生成额外的流量，应谨慎使用。来自电池供电设备的更新可能需要一些时间才能收到。

操作 zwave_js.set_value

此操作将在 Z-Wave 设备上设置一个值。它适用于需要修改节点状态但无法使用本机 Home Assistant 实体功能的高级用例。请注意，正确使用此操作需要对 Z-Wave 有深入了解。该操作提供最少的验证，并盲目调用 Z-Wave JS API，因此如果您在使用它时遇到问题，很可能是因为您在某处提供了不正确的值。要设置配置参数，您应该使用 zwave_js.set_config_parameter 或 zwave_js.bulk_set_partial_config_parameters 操作，而不是此操作。

操作 zwave_js.multicast_set_value

此操作将使用多播在多个 Z-Wave 设备上设置一个值。它适用于需要同时在多个节点上设置相同值的高级用例。请注意，正确使用此操作需要对 Z-Wave 有深入了解。该操作提供的验证最少，超出了正确调用 Z-Wave JS API 所需的验证，因此如果您在使用它时遇到问题，很可能是因为您在某处提供了不正确的值。

操作 zwave_js.invoke_cc_api

利用此操作直接使用命令类 API。在大多数情况下，zwave_js.set_value 操作将完成您需要的操作，但某些命令类具有无法通过该操作访问的 API 命令。有关可用 API 和参数的更多信息，请参阅 Z-Wave JS 命令类文档。在调用此操作时，请确保知道自己在做什么。

操作 zwave_js.refresh_notifications

此操作将刷新支持通知命令类的设备上的给定类型的通知。

操作 zwave_js.reset_meter

此操作将重置支持计量命令类的设备上的计量器。

操作 zwave_js.set_lock_configuration

此操作将设置锁的配置。

操作 zwave_js.set_lock_usercode

此操作将在代码槽 Y 中将锁的用户代码设置为 X。 有效的用户代码至少为 4 位数字。

操作 zwave_js.clear_lock_usercode

此操作将在代码槽 X 中清除锁的用户代码。 有效的代码槽在 1-254 之间。

事件

有两种类型的事件会触发，通知事件和值通知事件。您可以使用事件 Home Assistant 中的开发者工具 订阅 zwave_js_notification 或 zwave_js_value_notification 事件来测试收到的事件。一旦您知道事件数据的样子，您就可以使用它来创建自动化。

节点事件（通知）

请参阅 Z-Wave JS 通知事件文档 了解通知事件数据的解释。这些事件会触发 zwave_js_notification 事件类型。

通知事件数据可用于触发自动化，既可以在自动化 UI 中使用事件平台，也可以在 YAML 中使用事件平台。通过订阅 开发者工具 中的 zwave_js_notification 事件来检查事件的详细信息。

# 每当锁通过键盘解锁时触发。
triggers:
  - trigger: event
    event_type: zwave_js_notification
    event_data:
      node_id: 14
      event_label: "Keypad unlock operation"

通知命令类

这些是使用通知命令类的设备触发的通知事件。以下示例中的 parameters 属性是可选的，当包含时，属性中的键将根据事件的不同而有所不同。

{
    "domain": "zwave_js",
    "node_id": 1,
    "endpoint": 0,
    "home_id": "974823419",
    "device_id": "ad8098fe80980974",
    "command_class": 113,
    "command_class_name": "Notification",
    "type": 6,
    "event": 5,
    "label": "Access Control",
    "event_label": "Keypad lock operation",
    "parameters": {"userId": 1}
}

多级开关命令类

这些是使用多级开关命令类的设备触发的通知事件。有开始级别更改和停止级别更改的事件。这些通常用于具有外部开关的设备，例如 Aeotec Nano Dimmer，以响应长按按钮。

开始级别更改

{
    "domain": "zwave_js",
    "node_id": 1,
    "endpoint": 0,
    "home_id": 974823419,
    "device_id": "2f44f0d4152be3123f7ad40cf3abd095",
    "command_class": 38,
    "command_class_name": "Multilevel Switch",
    "event_type": 4,
    "event_type_label": "label 1",
    "direction": "up"
},

停止级别更改

{
    "domain": "zwave_js",
    "node_id": 8,
    "endpoint": 0,
    "home_id": 3803689189,
    "device_id": "2f44f0d4152be3123f7ad40cf3abd095",
    "command_class": 38,
    "command_class_name": "Multilevel Switch",
    "event_type": 5,
    "event_type_label": "label 2",
    "direction": null
},

入口控制命令类

这些是使用入口控制命令类的设备触发的通知事件。

{
    "domain": "zwave_js",
    "node_id": 1,
    "endpoint": 0,
    "home_id": "974823419",
    "device_id": "ad8098fe80980974",
    "command_class": 111,
    "command_class_name": "Entry Control",
    "event_type": 6,
    "event_type_label": "label 1",
    "data_type": 5,
    "data_type_label": "label 2",
    "event_data": "555"
}

场景事件（值通知）

值通知用于无状态值，例如 Central Scenes 和 Scene Activation。这些事件会触发 zwave_js_value_notification 事件类型。

值通知示例：

{
    "domain": "zwave_js",
    "node_id": 1,
    "home_id": "974823419",
    "endpoint": 0,
    "device_id": "ad8098fe80980974",
    "command_class": 91,
    "command_class_name": "Central Scene",
    "label": "Event value",
    "property": "scene",
    "property_name": "scene",
    "property_key": "001",
    "property_key_name": "001",
    "value": "KeyPressed",
    "value_raw": 0
}

值更新事件

由于某些设备不遵循 Z-Wave 规范，因此在某些情况下，设备会发送值更新，但 Home Assistant 中不会检测到状态更改。为了解决这个问题，可以监听 zwave_js_value_updated 事件，以捕获受影响实体接收到的任何值更新。此事件 在每个设备和每个实体域的基础上启用，并且实体将设置 assumed_state 为 true。此更改将影响这些实体的 UI 外观；如果您希望 UI 与未设置 assumed_state 为 true 的其他相同类型的实体匹配，可以通过 实体自定义 覆盖设置。

以下设备目前支持此事件：

值更新示例：

{
    "node_id": 4,
    "home_id": "974823419",
    "device_id": "ad8098fe80980974",
    "entity_id": "switch.in_wall_dual_relay_switch",
    "command_class": 37,
    "command_class_name": "Switch Binary",
    "endpoint": 0,
    "property": "currentValue",
    "property_name": "currentValue",
    "property_key": null,
    "property_key_name": null,
    "value": 0,
    "value_raw": 0
}

此事件可用于在需要获取新状态时触发值刷新。以下是一个自动化示例：

triggers:
  - trigger: event
    event_type: zwave_js_value_updated
    event_data:
      entity_id: switch.in_wall_dual_relay_switch
actions:
  - action: zwave_js.refresh_value
    data:
      entity_id:
        - switch.in_wall_dual_relay_switch_2
        - switch.in_wall_dual_relay_switch_3

自动化

Z-Wave 集成提供了自己的触发平台，可用于自动化。

zwave_js.value_updated

此触发平台可用于在任何 Z-Wave JS 值更新时触发自动化，包括 Home Assistant 不支持的 Z-Wave JS 值。虽然无法从自动化 UI 中编写，但可以直接在 configuration.yaml 中以 YAML 编写。

示例自动化触发配置

# 每当 `latchStatus` 值从 `closed` 更改为 `opened` 时触发自动化（设备将从实体 ID 中派生）。
triggers:
  - trigger: zwave_js.value_updated
    # 必须提供至少一个 `device_id` 或 `entity_id`
    device_id: 45d7d3230dbb7441473ec883dab294d4  # 车库门锁设备 ID
    entity_id:
      - lock.front_lock
      - lock.back_door
    # `property` 和 `command_class` 是必需的
    command_class: 98 # 门锁 CC
    property: "latchStatus"
    # `property_key` 和 `endpoint` 是可选的
    property_key: null
    endpoint: 0
    # `from` 和 `to` 都将接受值列表，如果值更新与任何列出的值匹配，则触发器将触发
    from:
      - "closed"
      - "jammed"
    to: "opened"

可用的触发数据

除了 标准自动化触发数据 之外，zwave_js.value_updated 触发平台还有其他触发数据可供使用。

zwave_js.event

此触发平台可用于在任何 Z-Wave JS 控制器、驱动程序或节点事件上触发自动化，包括 Home Assistant 可能不会自动处理的事件。有关可用事件及其随附数据的更多信息，请参阅链接的 Z-Wave JS 文档。

基于所有已知事件类型的严格验证，因此如果您遇到不支持的事件类型，请在 home-assistant/core 存储库中打开一个 GitHub 问题。

示例自动化触发配置

# 每当 `interview failed` 事件在三个设备上触发时触发自动化（设备将从设备和实体 ID 中派生）。
triggers:
  - trigger: zwave_js.event
    # 必须提供至少一个 `device_id` 或 `entity_id` 用于 `node` 事件。对于任何其他事件，需要提供 `config_entry_id`。
    device_id: 45d7d3230dbb7441473ec883dab294d4  # 车库门锁设备 ID
    entity_id:
      - lock.front_lock
      - lock.back_door
    config_entry_id:
    # `event_source` 和 `event` 是必需的
    event_source: node   # 选项是 node、controller 和 driver
    event: "interview failed"  # 事件名称可以从 Z-Wave JS 文档中获取（请参阅上面的链接）
    # `event_data` 和 `partial_dict_match` 是可选的。如果未包含 `event_data`，则给定上下文的所有事件类型都将触发自动化。当触发 `interview failed` 事件时，所有参数都位于 `event_data` 字典中的 `args` 键下的字典中。默认行为是要求完全匹配以下 event_data 字典和传递给事件的字典。通过将 `partial_dict_match` 设置为 true，Home Assistant 将检查 isFinal 参数是否为 true，并忽略字典中的任何其他值。如果此设置为 false，则此触发器永远不会触发，因为字典始终包含比 `isFinal` 更多的键，因此比较检查永远不会评估为 true。
    event_data:
      args:
        isFinal: true
    partial_dict_match: true  # 默认为 false

可用的触发数据

除了 标准自动化触发数据 之外，zwave_js.event 触发平台还有其他触发数据可供使用。

高级安装说明

如果您使用 Home Assistant Container、Home Assistant Core，或者不想使用内置的 Z-Wave JS 服务器插件，则需要自己运行 Z-Wave JS 服务器，Z-Wave 集成将连接到该服务器。

运行 Z-Wave JS 服务器

此应用程序提供了 Z-Wave USB 加密狗和 Home Assistant 之间的连接。Home Assistant Z-Wave 集成通过 WebSocket 连接连接到此服务器。您需要在使用集成之前运行此 Z-Wave JS 服务器。

有多种方式运行此服务器： 下图说明了仅适用于 Home Assistant OS 的选项 1 和 2。

选项 1：如上所述的官方 Z-Wave JS 插件

此选项仅适用于 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]（推荐的安装类型）和 Home Assistant SupervisedHome Assistant Supervised 是完整的 Home Assistant 生态系统，没有 Home Assistant 操作系统。 [Learn more] 安装。

此插件只能通过 Home Assistant 中内置的 Z-Wave 控制面板进行配置。如果您按照标准 安装程序 进行操作，这就是您运行 Z-Wave JS 服务器的方式。

选项 2：从社区插件商店安装的 Z-Wave JS UI 插件

此选项仅适用于 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]（推荐的安装类型）和 Home Assistant SupervisedHome Assistant Supervised 是完整的 Home Assistant 生态系统，没有 Home Assistant 操作系统。 [Learn more] 安装。

此插件包括 Z-Wave JS 服务器作为 Z-Wave JS UI 应用程序的一部分。可以通过 Home Assistant 中内置的 Z-Wave 控制面板以及 Z-Wave JS UI 内置的 Z-Wave 控制面板配置 Z-Wave 网络。它为您提供了一个功能齐全、外观吸引人且功能完整的 UI，用于管理您的 Z-Wave 节点和设置，随着 Z-Wave 控制面板开发的继续，它可能支持更高级的用例。

选项 3：Z-Wave JS UI Docker 容器

如果您运行 Home Assistant Container，这是推荐的方法。请参阅 Z-Wave JS UI 文档 了解安装说明。

此方法提供与 Z-Wave JS UI 插件相同的服务器应用程序和 UI。安装 Docker 镜像后，请确保在设置页面的 Home Assistant 部分启用 WS 服务器。

选项 4：自己运行 Z-Wave JS 服务器

这是一个非常高级的用例。在这种情况下，您直接运行 Z-Wave JS 服务器或 Z-Wave JS UI NodeJS 应用程序。安装和维护此内容超出了本文档的范围。有关信息，请参阅 Z-Wave JS 服务器 或 Z-Wave JS UI GitHub 存储库。

在 Home Assistant 中安装和配置 Z-Wave 集成

一旦您启动并运行了 Z-Wave JS 服务器，您需要在 Home Assistant 中安装和配置集成（如上所述）。

如果您运行完整的 Home Assistant 并且有 supervisor，系统会显示一个对话框，询问您是否要使用 Z-Wave JS Supervisor 插件。如果您以官方 Z-Wave JS 插件以外的任何方式运行 Z-Wave JS 服务器，包括使用 Z-Wave JS UI 插件，则必须取消选中此框。

如果您没有运行 supervisor 或者您取消选中了上述框，系统会要求您输入 WebSocket URL（默认为 ws://localhost:3000）。在此处填写正确的（Docker）IP/主机名非常重要。例如，对于 Z-Wave JS UI 插件，这是 ws://a0d7b954-zwavejs2mqtt:3000。

常见问题：支持的设备和命令类

有关支持的设备列表，请参阅 Z-Wave JS 设备数据库。

虽然支持最常见的设备，但某些命令类尚未（完全）在 Z-Wave JS 中实现。您可以在 此处 跟踪状态。

您还可以查看 Z-Wave 命令类 Home Assistant 在查询时响应的列表 在页面末尾。

您还可以在 此处 跟踪 Z-Wave 集成的路线图。

常见问题：安装和配置

我应该购买哪个 Z-Wave 控制器？

Z-Wave 支持所有已知的 500 和 700 系列 Z-Wave 控制器。如果您刚刚开始，我们建议您购买 700 系列控制器（固件更新到 >=7.17.2）。

有关更多信息，请参阅 支持的 Z-Wave 加密狗

为什么我（未）自动提示安装 Z-Wave？

某些 Z-Wave USB 加密狗可以自动发现，这可以简化 Z-Wave 设置过程。以下设备已通过发现测试，并提供快速设置体验；然而，这些并不是 Z-Wave 支持的所有设备：

其他设备可能是可发现的，但仅列出了已确认可发现的设备。

Zwavejs2Mqtt 或 Z-Wave JS 到 MQTT 插件发生了什么？

Zwavejs2Mqtt 于 2022 年 9 月更名为 Z-Wave JS UI。它们在功能上没有区别。

我可以在 Z-Wave JS 和 Z-Wave JS UI 之间切换吗？

您可以在官方 Z-Wave JS 插件和 Z-Wave JS UI 插件之间切换。但是，您不能同时运行它们。一次只能激活其中一个。

如何在 Z-Wave JS 和 Z-Wave JS UI 之间切换？

要在官方 Z-Wave JS 插件和 Z-Wave JS UI 插件之间切换，请按照以下步骤操作：

切换不需要重命名您的设备。

1. 禁用 Z-Wave 集成。不要删除 Z-Wave 集成，否则您将丢失所有设备和实体命名。 这将自动停止官方 Z-Wave JS 插件。

2. 记下官方插件中的网络安全密钥。

3. 安装并启动 Z-Wave JS UI 插件。

4. 使用添加的控制面板配置 Z-Wave JS UI 插件，包括设置 Z-Wave 设备的位置和网络安全密钥。

5. 再次添加 Z-Wave 集成（即使它仍然安装），并取消选中“使用 Z-Wave JS Supervisor 插件”。在下一步的 URL 字段中输入社区插件的正确地址。

6. 卸载官方 Z-Wave JS 插件。

7. 启用 Z-Wave 集成。

使用 Z-Wave JS UI 插件有什么好处？

您可能想知道使用 Z-Wave JS UI 插件而不是官方插件有什么好处。 官方插件提供了最低限度的 Z-Wave 服务器，仅足以为 Home Assistant 集成提供服务。

Z-Wave JS UI 项目包括 Z-Wave JS 服务器以方便使用，但也提供了一个 Z-Wave 控制面板，并能够将您的 Z-Wave 网络提供给 MQTT。这允许您使用控制面板，如果您愿意，还可以同时使用 MQTT。例如，一些用户可能会使用 MQTT 从其他设备与 Z-Wave 交互，而 Home Assistant 集成仍然可以正常工作（只要您在 Z-Wave JS UI 中保持启用 WS 服务器）。

Z-Wave JS UI 也提供 HA 设备的发现，现在我很困惑

正确，Z-Wave JS UI 项目在 Home Assistant 计划转向 Z-Wave JS 驱动程序之前就已经存在。您应该使用集成进行设备发现，而不是 Z-Wave JS UI 提供的 MQTT 发现。

我可以仅运行 Z-Wave JS UI 以用于控制面板而不做其他事情吗？

当然，在 Z-Wave JS UI 的设置中，确保启用“WS 服务器”并禁用“网关”。

我应该在 Home Assistant 中命名我的设备，还是在 Z-Wave JS UI 中命名？

最终，这是一个个人决定。如果您在 Z-Wave JS UI 中为设备提供名称或位置，则在重新加载集成或重新启动 Home Assistant 时，该名称将导入到 Home Assistant 中。但是，如果设备已经由 Home Assistant 设置，则不会更改任何实体名称。在 Z-Wave JS UI 中设置的名称不会覆盖已在 Home Assistant 中进行的更改。

在 Home Assistant 中设置的名称不会导入到 Z-Wave JS UI 中。

我应该使用 Secure Inclusion 吗？

这取决于。Z-Wave 加密有两代，Security S0 和 Security S2。两者都提供加密并允许检测数据包损坏。

Security S0 会对您的网格产生显著的额外流量，仅推荐用于不支持 Security S2 但需要加密才能正常工作的旧设备，例如门锁。

Security S2 不会产生额外的网络流量，并提供额外的好处。例如，使用 S2 的终端设备要求集线器报告它们的报告是否已接收并理解。

默认情况下，Z-Wave 更喜欢 Security S2（如果支持）。仅在绝对必要时使用 Security S0。

在 Z-Wave JS 插件中可以看到安全密钥吗？

在 Z-Wave 控制器的初始设置后，您可以在 Z-Wave JS 插件中查看安全密钥。转到 设置 > 插件 > Z-Wave JS 并打开 配置 选项卡。您现在可以看到三个 S2 密钥和 S0 密钥。网络安全密钥是一个遗留配置设置，与 S0 密钥相同。

常见问题：故障排除主题

我遇到了问题，首先该怎么办？

许多 报告的问题是由于系统的 USB 端口引起的 RF 干扰。这可能以多种方式表现出来，包括设备根本无法包含、设备无法安全包含、传感器值错误（数据包损坏）、设备控制延迟或无法控制设备。

建议所有用户使用 USB 延长线以防止此类干扰。 在打开问题或在 Discord 上请求支持之前，请尝试使用此类电缆。无论如何，这几乎总是我们要求您采取的第一个故障排除步骤。

确保使用延长线后，重建网络路由。

这两个步骤的结合解决了大量报告的困难。

我有一个 Aeotec Gen5 控制器，它在我的 Raspberry Pi 4 上未被检测到？

第一代 Gen5 控制器在插入 Pi 4 和可能其他系统时存在已知错误。Aeotec 发布了 Gen5+ 加密狗以纠正此错误。Gen5 用户可以将其加密狗插入 USB 2.0 集线器以克服此问题。

我在 Home Assistant 中没有看到为我的设备创建的任何实体

仅在节点准备就绪（采访完成）后才会创建实体。此外，请注意某些设备（如按钮遥控器）不会创建任何实体，但在按下按钮时只会提供事件。请参阅事件部分，了解如何在自动化中处理这些事件。

如果您确定您的设备应该有实体，但您没有看到它们（即使在重新启动 Home Assistant Core 后），请在 GitHub 问题跟踪器上创建一个关于您的问题的问题。

如果我手动控制设备，设备不会自动更新其在 HA 中的状态

您的设备可能不会向控制器发送自动状态更新。虽然最好的建议是更新到最近的 Z-Wave Plus 设备，但可以通过主动轮询（请求状态）来解决。

Z-Wave 不会定期自动轮询设备。轮询很容易导致网络拥塞，应谨慎使用，仅在必要时使用。

• 我们提供了 zwave_js.refresh_value 操作，允许您手动轮询值，例如从在同一房间内有运动时仅轮询设备的自动化中。如果您 确实 需要轮询，可以在 Z-Wave JS UI 中启用此功能，但不能在官方插件中启用。

• Z-Wave JS UI 允许您在每个值的基础上配置计划轮询，您可以使用它来保持某些值的更新。它还允许您从自动化中按需轮询单个值，这应优先于盲目轮询所有时间。

我的设备被识别为未知制造商和/或某些功能在 Z-Wave 集成中不起作用

当您的设备尚未完全采访时，此信息将不会出现。因此，请确保您的设备至少采访一次。

如果采访完成，则设备尚未具有 Z-Wave JS 的设备文件。与其他 Z-Wave 驱动程序不同，即使没有这样的文件，您的设备也可能会按预期工作。如果您的设备未完全支持，请考虑 贡献设备配置文件。

如何获取当前网络状态的转储？

在尝试确定某些内容未按预期工作时，或在报告集成问题时，了解 Z-Wave JS 视为当前 Z-Wave 网络状态的信息是有帮助的。要获取当前网络状态的转储，请按照以下步骤操作：

1. 转到 设置 > 设备和服务。
2. 选择 Z-Wave 集成。然后，选择三个点。
3. 从下拉菜单中选择 下载诊断。

如何解决干扰问题？

许多用户报告了在 USB 加密狗直接连接到机器（接近）时的干扰问题。如果您遇到问题，请尝试使用短的 USB 2.0 A（公对母）延长线。

如何访问 Z-Wave 日志？

简单方法

启用 Z-Wave JS 日志记录

1. 转到 Z-Wave 集成面板：
2. 在屏幕左侧选择 启用调试日志记录。

日志级别将设置为 debug，适用于集成、库和驱动程序（如果驱动程序日志级别尚未设置为 verbose、debug 或 silly），并且所有 Z-Wave JS 日志将添加到 Home Assistant 日志中。

禁用 Z-Wave JS 日志记录

1. 转到 Z-Wave 集成面板：
2. 在屏幕左侧选择 禁用调试日志记录。

日志级别将重置为其先前的值，适用于集成、库和驱动程序，并且前端将自动发送您在此期间生成的 Z-Wave 日志以供下载。

高级方法

手动启用 Z-Wave JS 日志记录，或通过自动化启用

将 zwave_js_server 的日志级别设置为 debug。这可以在 configuration.yaml 中的 logger 部分完成，也可以使用 logger.set_level 操作完成。当集成检测到日志级别已设置为 debug 时，如果级别尚未设置为 verbose、debug 或 silly，它还会将 Z-Wave JS 日志设置为 debug，并将这些日志包含在 Home Assistant 日志中。Z-Wave JS 日志可以在记录器名称 zwave_js_server.server 下找到。

手动禁用 Z-Wave JS 日志记录，或通过自动化禁用

将 zwave_js_server 的日志级别设置为高于 debug 的级别。这可以在 configuration.yaml 中的 logger 部分完成，也可以使用 logger.set_level 操作完成。Z-Wave JS 日志将不再包含在 Home Assistant 日志中，如果集成更改了 Z-Wave JS 的日志级别，它将自动更改回其原始级别。

不支持的功能

本节列出了 Z-Wave 中可用但当前在 Home Assistant 中不支持的功能。

将控制器设置为学习模式以接收网络信息

在 Home Assistant 中，当前无法将 Z-Wave 控制器设置为学习模式以接收来自其他控制器的网络信息。

使用 经典包含 在现有网络中包含/排除控制器

管理空网络的 Z-Wave 控制器也可以加入不同的网络并在那里充当辅助控制器。然而，在 Home Assistant 中，这是不可能的。Home Assistant 不允许 Z-Wave 控制器加入其他网络，因为 Home Assistant 充当中央集线器。

Z-Wave 关联组

在 Home Assistant 中，实现了一个 关联组：

• 组 1：这是一个仅包含一个设备的关联组。它在 恢复出厂设置 后用于发送 设备本地重置通知。

此关联组在 Home Assistant 重置 Z-Wave 控制器 时使用。

在正常情况下，不需要将设备添加到此组。

通过 Z-Wave 进行识别

其他 Z-Wave 设备可以通过发送以下 Indicator Set Z-Wave 命令指示 Home Assistant 实例进行识别（所有字节均为十六进制）：

87010003500308500403500506
            ~~    ~~    ~~

用 ~ 下划线的字节也可以有任何其他值。

当接收到此类命令时，Home Assistant 将在其侧边栏中显示一条通知，提到哪个节点发送了该命令。

Z-Wave 命令类 Home Assistant 在查询时响应

下表列出了命令类及其实现的版本和所需的安全类。这些是 Home Assistant 在其他设备查询时会响应的命令类。

Z-Wave 术语

本节解释了您可能在 Z-Wave 产品文档中找到的一些 Z-Wave 术语和概念。

关联组

在 Z-Wave 术语中，关联 是指两个或多个 Z-Wave 产品直接通信。这使得设备可以在不通过集线器通信的情况下相互通信，或者向中央集线器发送未经请求的报告。

在 Z-Wave 术语中，关联组 是指在某些情况下将命令发送到的设备组。关联组及其功能特定于发送命令的设备。有关详细信息，请参阅设备手册。

SmartStart

支持 SmartStart 的产品可以通过使用支持 SmartStart 包含的控制器扫描产品上的 Z-Wave QR 码添加到 Z-Wave 网络中。 无需进一步操作，SmartStart 产品将在打开电源后 10 分钟内自动添加到网络范围内。并非所有设备都支持 SmartStart。某些设备需要 经典包含。有关将设备添加到 Home Assistant 的文档，请参阅 将新设备添加到 Z-Wave 网络。

术语映射表

对于某些概念，Home Assistant 中使用的术语与 Z-Wave 文档中使用的术语不对应。请参阅 术语映射表 了解术语等价物列表。