Z-Wave#

Z-Wave 集成允许您通过 Z-Wave JS 驱动程序从 Home Assistant 控制 Z-Wave 网络。

#入门

本节介绍如何设置 Z-Wave 网络以及如何将 Z-Wave 终端设备添加到该网络。

Home Assistant 中的 Z-Wave 网络包括以下元素：

• Z-Wave 适配器（例如 Home Assistant Connect ZWA-2）
• Z-Wave 服务器（例如 Z-Wave JS 应用程序，以前称为插件）
• 此 Z-Wave 集成
• Z-Wave 终端设备

#在 Home Assistant 中设置 Z-Wave 服务器

本节介绍如何在 Home Assistant 中使用 Z-Wave JS 应用程序设置 Z-Wave 服务器。

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

设置完 Z-Wave 服务器后，您可以向网络添加设备。

#前提条件

• 支持的 Z-Wave 适配器。
  • 首次使用？有关推荐，请参阅应该购买哪种 Z-Wave 适配器。

#设置 Z-Wave 服务器

1. 打开 Home Assistant 用户界面。

2. 将 Z-Wave 适配器插入运行 Home Assistant 的设备。

   • 您的适配器很可能会被自动识别。
   • 在对话框中，选择 推荐安装。
     • 这将在 Home Assistant 服务器上安装 Z-Wave JS 应用程序。
   • 将设备添加到区域并选择 完成。
   • 故障排除：如果您的适配器未被自动识别，请按照这些步骤操作。

3. 等待安装完成。

4. 根据您的 Home Assistant 版本，您可能会被提示输入网络安全密钥。

   • 如果您是首次使用 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 中，转到 设置 > Z-Wave。
2. 选择 添加设备。
   • Z-Wave 适配器现在处于添加模式。
3. 检查您的设备是否支持 SmartStart：
   • 在包装上检查 SmartStart 标签。
   • 找到二维码。它可以在包装上或设备本身上。
4. 根据您的设备是否支持 SmartStart，按照选项 1 或 2 中的步骤操作：
   • 选项 1：您的设备支持 SmartStart：
     • 确保设备已关闭。
     • 选择 扫描二维码 并扫描设备上的二维码。
       • 故障排除：如果扫描不起作用（例如由于缺少 HTTPS），请从其他二维码阅读器粘贴二维码内容作为文本，然后选择 提交。
     • 如果设备支持 Z-Wave Long Range，您将被提示选择网络类型。
       • Long Range：如果它远离其他设备，或者该位置过去有连接问题。这也可能有助于延长电池寿命。
       • Mesh：如果您已经有网格网络。添加它可以增强此网络的覆盖范围和可靠性。
       • 您随时可以移除并重新配对设备以切换到其他网络类型。
     • 打开设备并将其设置为添加模式。
       • 如果已经打开，您可能需要重新通电。
   • 选项 2：您的设备不支持 SmartStart：
     • 将设备设置为添加模式。请参阅设备手册了解如何操作。
     • 如果您的设备使用 S2 安全添加，您可能会被提示输入设备提供的 PIN 码。通常，此 PIN 码随文档提供，并且也印在设备本身上。有关安全添加的更多信息，请参阅本节。
5. 界面应确认设备已添加。稍等片刻（几秒到几分钟），实体也应该被创建。
6. 故障排除：如果适配器无法添加/找到您的设备，请取消添加过程。
   • 在某些情况下，在添加设备之前先移除设备（排除）可能会有所帮助，即使该设备尚未添加到此 Z-Wave 网络。
   • 另一种方法是将设备恢复出厂设置。请参阅设备手册了解如何操作。

重要：

1. 不要移动您的 Z-Wave 适配器来添加设备。 移动适配器已不再必要，并且会导致路由中断。
2. 不要从 Z-Wave 适配器本身启动设备添加。 这已不再支持。

#从当前 Z-Wave 网络移除设备

在将设备与其他适配器一起使用之前，或者当您不再使用该设备时执行此操作。它从存储在适配器上的 Z-Wave 网络中移除设备。它还从 Home Assistant 中移除设备及其所有实体。如果设备仍与适配器配对，则无法将其加入新网络。

1. 在 Home Assistant 中，转到 设置 > 设备与服务。
2. 选择 Z-Wave 集成。
   • 然后，选择要移除的设备。
3. 在 设备信息 下，选择三点 菜单，然后选择 删除。
   • 这将打开一个包含移除设备选项的对话框。
4. 选择 移除正常工作的设备。
   • Z-Wave 适配器现在处于排除模式。
5. 将要移除的设备设置为排除模式。请参阅其手册了解如何操作。
6. 界面应确认设备已移除，设备和实体将从 Home Assistant 中移除。

#从外部 Z-Wave 网络移除设备

当您有一个仍与适配器配对的设备，但您不再有该适配器的访问权限时执行此操作。如果设备未从该适配器中排除，则无法将其加入新网络。此过程从以前的适配器网络中移除设备，允许您将其与新适配器配对。

1. 在 Home Assistant 中，转到 设置 > Z-Wave。
2. 选择 选项。
3. 在 移除外部设备 旁边，选择 移除 > 开始排除。
4. 将要移除的设备设置为排除模式。请参阅其手册了解如何操作。
5. 界面应确认设备已移除，设备和实体将从 Home Assistant 中移除。

#将 Z-Wave 网络迁移到新适配器

如果您有现有的 Z-Wave 网络并希望用新适配器替换其适配器，请执行此操作。带有所有实体的 Z-Wave 集成将保留在 Home Assistant 中。新适配器被添加到 Home Assistant 并与现有网络配对。

#前提条件

• Home Assistant 管理员权限

#特定设备的前提条件

#将 Z-Wave 网络迁移到新适配器

1. 在 Home Assistant 中，转到 设置 > Z-Wave。
2. 在 迁移适配器 下，选择 迁移。
3. 当显示 拔掉您的适配器 对话框时，拔掉您的旧适配器。
   • 现在移除旧设备很重要，因为它可能会干扰新设备。即使它可能不会立即抛出错误，也可能会导致问题。
4. 连接新适配器。
5. 选择 提交。
6. 在 选择您的设备 对话框中，选择您刚刚连接的 Z-Wave 适配器。
   • 通常，您可以选择连接到 USB 端口的设备。
   • 要连接到通过 TCP 暴露的 Z-Wave 控制器（如 Portable Z-Wave），请选择 使用套接字 选项。
7. 选择 提交。
   • 新适配器现在正在与您现有的 Z-Wave 网络配对。
   • 故障排除：如果迁移失败，可能是因为您错误地选择了 使用套接字。如果您使用的是基于 USB 的控制器，请重新插入旧适配器，并等待网络重新加载。
     • 一旦旧适配器连接并且网络运行正常，请重复迁移步骤。
     • 确保这次选择新控制器（而不是 使用套接字）。
8. 迁移完成后，检查是否要重命名适配器。如果您之前更改过名称，新适配器可能会保留旧适配器的名称。
   • 在左上角，选择返回按钮返回集成页面。
   • 在设备列表中，检查设备名称。
   • 要更改设备名称，请选择 按钮。

#从 Z-Wave JS UI 迁移到 Z-Wave JS 应用程序

如果您一直在使用 Z-Wave JS UI 应用程序，可以迁移到 Z-Wave JS 应用程序，而无需重新配对设备。Z-Wave JS 应用程序是 Z-Wave JS UI 应用程序的继任者，提供更好的体验和更多功能。迁移过程涉及安装 Z-Wave JS 应用程序，它将自动接管 Z-Wave JS UI 应用程序。

#前提条件

• Home Assistant 管理员权限
• 您的 Z-Wave 网络当前由 Z-Wave JS UI 应用程序管理

#安装必要的应用程序

1. 在 Home Assistant 中，转到 设置 > 应用程序 > Z-Wave JS。
2. 通过选择 安装 来安装 Z-Wave JS 应用程序。
   • 暂时不要启动应用程序。
3. 安装必要的辅助应用程序：
   • 安装 Terminal & SSH 应用程序，以便您可以在 Home Assistant 主机上运行命令。
   • 安装一个让您在 Home Assistant 主机上上传和编辑文件的应用程序，如 File Editor 应用程序 或 Studio Code Server 应用程序。

#从 Z-Wave JS UI 下载备份

1. 打开 Z-Wave JS UI Web 界面并转到 Store 选项卡。

   

2. 下载备份：

   • 在右下角，选择 Download。

   

3. 停止 Z-Wave JS UI 应用程序。

#运行迁移脚本

1. 从 https://gist.github.com/AlCalzone/eb0947a39a3ff91c053f259f0ac4efc3#file-migrate_to_zwave_js_app-sh 下载迁移脚本 .zip 文件。

2. 解压 zip 文件并找到 migrate_to_zwave_js_app.sh 脚本。

3. 找到您从 Z-Wave JS UI Web 界面下载的备份文件。它应该是一个 .zip 文件。

4. 打开 Studio Code Server 或 SSH 应用程序。

5. 将备份文件和迁移脚本上传到临时文件夹，最好是 /tmp 文件夹。

6. 打开终端，然后使用 cd /tmp 导航到 /tmp 文件夹。

   

7. 通过运行 chmod +x ./migrate_to_zwave_js_app.sh 使脚本可执行

   

8. 运行 ./migrate_to_zwave_js_app.sh <backup-filename>，然后按照屏幕上的说明操作：

   

#重新配置 Z-Wave 集成以使用 Z-Wave JS 应用程序

1. 转到 设置 > 设备与服务。

2. 选择三点 菜单，然后选择 重新配置。

   

3. 选择 重新配置当前适配器。

   

4. 根据您的控制器连接方式，您可能需要选择或清除 使用 Z-Wave Supervisor 应用程序 复选框。

   • 选项 1： 如果您使用的是基于 USB 或基于 TCP 的控制器：

     • 选择 使用 Z-Wave Supervisor 应用程序 复选框。

       

     • 在下一步中，选择您的控制器并选择 提交。

       

   • 选项 2： 如果您使用的是 GPIO 模块或您的控制器未显示在列表中：

     • 清除 使用 Z-Wave Supervisor 应用程序 复选框。

       

     • 输入 Z-Wave JS 应用程序的连接详细信息：

       • 在 URL 字段中，输入 ws://core-zwave-js:3000。

       

5. 删除您为迁移上传到 /tmp 文件夹的临时文件。

6. 完成！您的 Z-Wave JS 应用程序现在正在管理您的 Z-Wave 网络。您可以启动 Z-Wave JS 应用程序并停止和卸载 Z-Wave JS UI 应用程序。

#在 Z-Wave JS 应用程序中覆盖适配器的无线电频率区域

Z-Wave 设备使用的频率取决于您所在的地区。对于 700 和 800 系列适配器，此频率可以更改。终端设备的频率不能更改，因此您需要购买特定于您所在地区的设备。

如果您使用的是 Z-Wave JS 应用程序，Home Assistant 会自动更改无线电频率区域以匹配您所在的国家/地区。如果需要，您可以覆盖此设置。

#前提条件

• Home Assistant 管理员权限
• 您的所有 Z-Wave 设备必须指定用于该区域
• 注意：此过程仅适用于您的适配器是使用 Z-Wave JS 应用程序设置的情况

#覆盖 Z-Wave 适配器的无线电频率区域

1. 转到 设置 > 应用程序 > Z-Wave JS。
2. 打开 配置 选项卡。
3. 在 选项 部分，选择 无线电频率区域。
   • 自动 根据 设置 > 系统 > 常规 下定义的位置设置区域。
   • 对于支持 Long Range 的地区，如果适配器支持，它将使用 Long Range。
   • 如果您手动设置区域，请选择可用的 Long Range 选项之一：
     • 欧洲（Long Range） 或 美国（Long Range）。
   • 即使选择了 Long Range 选项，您仍然可以添加不支持 Long Range 的设备。
4. 要应用更改，选择 保存。
   • 您的 Z-Wave 适配器现在已准备好与指定用于所选区域的设备通信。
5. 要返回默认设置并使用 Home Assistant 定义的区域，在 无线电频率区域 下选择 自动。

#备份您的 Z-Wave 网络

建议在对 Z-Wave 网络进行任何重大更改之前创建备份。例如，在从一个适配器迁移到另一个适配器之前，或在重置适配器之前。备份存储您的 Z-Wave 适配器的非易失性存储器（NVM），其中包含您的网络信息，包括配对的设备。它存储在一个可以下载的二进制文件中。

#前提条件

• Home Assistant 管理员权限

#备份 Z-Wave 网络

1. 在 Home Assistant 中，转到 设置 > Z-Wave。
2. 在 下载备份 下，选择 下载。
   • 结果：备份文件下载到您发起下载的设备。
3. 完成！将备份文件存储在安全的地方，以便以后需要恢复 Z-Wave 网络时使用。

#从备份恢复 Z-Wave 网络

您可以从备份恢复 Z-Wave 网络。

#前提条件

• Home Assistant 管理员权限
• 已下载备份

#从备份恢复 Z-Wave 网络

1. 在 Home Assistant 中，转到 设置 > Z-Wave。
2. 在 从备份恢复 下，选择 恢复。
   • 选择要从其恢复的备份。
   • 结果：Z-Wave 网络正在恢复，属于该网络的设备应该会重新出现。

#更新 Z-Wave 设备的固件

具有固件更新元数据命令类的适配器和设备允许您通过上传固件文件来更新固件。在这些情况下，您可以从 Home Assistant 中的设备页面启动固件更新。请参阅设备制造商的文档以找到相应的固件文件。一个例子是 Zooz 的固件页面。

#前提条件

• Home Assistant 管理员权限
• 从制造商网站下载的固件文件

#更新 Z-Wave 设备的固件

1. 在 Home Assistant 中，转到 设置 > Z-Wave。
2. 选择 设备。
   • 然后选择要更新的设备。
3. 在 设备信息 下，选择三点 菜单，然后选择 更新。
4. 选择您之前下载到计算机的固件文件。
   • 注意：设备损坏风险
     • 确保选择正确的固件文件。
       • 错误的固件文件可能会损坏您的设备。
     • 一旦开始更新过程，必须等待更新完成。
       • 中断的更新可能会损坏您的设备。
5. 选择 开始固件更新 并等待其完成。

#重置 Z-Wave 适配器

建议在重置设备之前备份 Z-Wave 网络。

• 适配器将忘记所有与其配对的设备。

• 此网络的所有 Z-Wave 设备将从 Home Assistant 中移除。

• 如果重置时仍有设备与适配器配对，它们必须经过排除过程才能重新配对。

• 设备固件将保留在设备上。

#前提条件

• Home Assistant 管理员权限
• 备份您的 Z-Wave 网络
• 从网络中移除所有与适配器配对的设备。
  • 移除可以由任何适配器完成，而不仅仅是原本管理网络的适配器。理论上，这也可以稍后完成。

#重置 Z-Wave 适配器

1. 在 Home Assistant 中，转到 设置 > 设备与服务。

2. 选择 Z-Wave 集成。然后，选择控制器。

3. 在 设备信息 下，选择三点 菜单，然后选择 恢复出厂设置。

   

4. 在设备信息页面上，检查 活动 面板。当您看到状态实体变为不可用时，重置过程已完成。

   • 您现在可以拔掉适配器并使用它来启动新网络，或将其传递给其他人。

5. 如果您不再需要 Z-Wave 集成，可以从 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 设备或启动添加新设备到网络的添加过程。

我的网络 部分让您访问 Z-Wave 网络的设备和实体列表。

• 显示地图：允许您查看 Z-Wave 网络的可视化表示，显示设备和它们之间的路由。这有助于排查网络中的问题。

• 选项 > 移除设备：启动从网络中移除外部设备的排除过程。这允许您移除仍与另一个 Z-Wave 适配器配对的设备。

• 选项 > 发现并分配新路由：发现适配器和设备之间的新路由。当设备或适配器移动到新位置，或者您的网络存在严重问题时，这很有用。发现过程会产生大量网络流量，应谨慎使用。

• 统计：提供有关适配器和其他设备之间通信的统计信息，让您排查网络的 RF 质量。

• 日志：提供对 Z-Wave JS 日志的访问，这有助于排查网络问题。

• 分析：允许您选择加入或退出 Z-Wave JS 项目收集的遥测数据，以帮助开发和制造商做出明智的决定。此遥测默认禁用，必须选择加入才能激活。

• 网络信息：有关 Z-Wave 网络的元数据，例如 Home ID、服务器版本或服务器 URL。此信息在排查网络问题或联系支持时很有帮助。

• 下载备份：创建并下载 Z-Wave 网络的备份。备份包含 Z-Wave 适配器的非易失性存储器（NVM），其中包括所有配对的设备。建议在对 Z-Wave 网络进行任何重大更改之前创建备份，例如迁移到新适配器或重置适配器。

• 从备份恢复：从您之前下载的备份文件恢复 Z-Wave 网络。这在迁移到新适配器时，或者在重置适配器后想要恢复网络时很有帮助。

• 迁移适配器：允许您将 Z-Wave 网络迁移到新适配器。

#关于网络信息

集成配置面板中的 网络信息 部分显示有关 Z-Wave 网络和运行它的软件的元数据。此信息在排查问题或联系支持时很有用。

• Home ID：分配给您 Z-Wave 网络的唯一标识符。配对到您网络的每个设备都共享此 ID。它可用于验证设备是否属于您的网络，或在寻求帮助时识别您的网络。
• 驱动版本：Z-Wave JS 服务器上运行的 Z-Wave JS 驱动程序版本。驱动程序是直接与您的 Z-Wave 适配器通信的核心库。
• 服务器版本：您设置中运行的 Z-Wave JS 服务器版本。服务器充当 Z-Wave JS 驱动程序和 Home Assistant 之间的桥梁。
• 服务器 URL：Home Assistant 用于连接到 Z-Wave JS 服务器的 WebSocket URL，例如 ws://homeassistant.local:3000。这在您需要验证或重新配置 Home Assistant 和 Z-Wave JS 服务器之间的连接时很有用。

#集成菜单

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

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

#网络设备

以下功能可以从您网络上任何 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) 部分参数的不同方式示例。注意在我们为同一键使用不同值的地方，这些不同值在示例中可以互换使用。例如，我们可以在所有示例中为 value 互换使用 1 或 Blink。

示例 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）。

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

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

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

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

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"

"1":
  usercode: "1234"
  in_use: true
"2":
  usercode: ""
  in_use: false

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

{
    "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}
}

{
    "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"
}

{
    "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
}

{
    "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

# 当 `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 # Door Lock CC
    property: "latchStatus"
    # `property_key` 和 `endpoint` 是可选的
    property_key: null
    endpoint: 0
    # `from` 和 `to` 都将接受值列表，如果值更新与列出的任何值匹配，则触发
    from:
      - "closed"
      - "jammed"
    to: "opened"

# 当 `interview failed` 事件在三个设备上触发时触发（设备将从设备和实体 ID 派生）。
triggers:
  - trigger: zwave_js.event
    # 对于 `node` 事件，必须至少提供一个 `device_id` 或 `entity_id`。对于任何其他事件，需要提供 `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

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

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

如果您运行带有 supervisor 的完整 Home Assistant，您将看到一个对话框，询问您是否要使用 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 和 800 系列 Z-Wave 适配器。如果您刚开始使用，我们建议您购买 800 系列适配器（固件更新至 >=7.23.2）。

有关更多信息，请参阅支持的 Z-Wave 适配器

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

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

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

#Zwavejs2Mqtt 或 Z-Wave JS to MQTT 应用程序发生了什么？

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

#Z-Wave JS UI 应用程序发生了什么？

Z-Wave JS UI 应用程序正在逐步淘汰，因为其功能丰富的 UI 现在已包含在 Z-Wave JS 应用程序中。Z-Wave JS UI 应用程序将继续支持一段时间，但鼓励用户切换到 Z-Wave JS 应用程序。

#我应该使用安全添加吗？

这取决于。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 上请求支持之前尝试使用此类延长线。这几乎总是我们会要求您采取的第一个故障排除步骤。

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

这两个步骤的组合可以纠正大量报告的困难。

#我的 Z-Wave 适配器在设置期间未被自动识别

如果您的 Z-Wave 适配器没有自动显示在 已发现 部分，请尝试手动添加：

1. 检查硬件：
   • 确保适配器已通电。
   • 确保您使用的电缆支持数据传输，而不仅仅是电源。
2. 转到 设置 > 设备与服务。
3. 在右下角，选择 Add integration 按钮并选择 Z-Wave。
4. 按照屏幕上的说明完成设置。
5. 如果仍未发现，请检查干扰。

#我有一个 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 允许您在每个值的基础上配置定时轮询，您可以使用它来保持某些值更新。它还允许您从自动化中按需轮询单个值，如果可能，这应该优于盲目地一直轮询。

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

当您的设备尚未完全查询时，此信息尚不存在。因此，请确保您的设备至少被查询过一次。

如果查询已完成，则该设备尚无 Z-Wave JS 的设备文件。与其他 Z-Wave 驱动程序不同，即使没有此类文件，您的设备也可能按预期工作。如果您的设备未完全支持，请考虑贡献设备配置文件。

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

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

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

#如何解决干扰问题？

许多用户报告当适配器直接连接到机器（近距离）时会出现干扰问题。如果您遇到问题，请尝试使用短的 USB 2.0 A（公对母）延长线。

#如何访问 Z-Wave 日志？

#简单方法

#启用 Z-Wave JS 日志记录

1. 转到 Z-Wave 集成面板：
2. 在右上角，选择三点 菜单并选择 启用调试日志记录。
   • 结果：集成、库和可选驱动程序（如果驱动程序日志级别尚未设置为 verbose、debug 或 silly）的日志级别将设置为 debug，所有 Z-Wave JS 日志将添加到 Home Assistant 日志中。
3. 如果您想更改日志级别，在 Z-Wave 集成面板上：，选择齿轮 。
   • 选择 日志 选项卡，然后选择日志级别。

#禁用 Z-Wave JS 日志记录

1. 转到 Z-Wave 集成面板：
2. 在右上角，选择三点 菜单并选择 禁用调试日志记录。
   • 结果：集成、库和驱动程序的日志级别将重置为其先前的值，Home Assistant 前端将自动向您发送在此期间生成的 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

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

#SmartStart

启用 SmartStart 的产品可以通过扫描产品上的 Z-Wave 二维码添加到 Z-Wave 网络中，适配器需支持 SmartStart 添加。 无需进一步操作，SmartStart 产品将在开机后 10 分钟内自动添加到网络范围内。并非所有设备都支持 SmartStart。某些设备需要_经典添加_。有关向 Home Assistant 添加设备的文档，请参阅向 Z-Wave 网络添加新设备。

#术语映射表

本文档中使用 Home Assistant 术语。对于某些概念，术语与 Z-Wave 文档中使用的术语不对应。下表提供了其中一些术语的对应关系。

#从 Home Assistant 移除 Z-Wave JS

这将从 Home Assistant 中移除所有配对的 Z-Wave 设备及其实体、Z-Wave JS 应用程序和 Z-Wave 集成。

#从 Home Assistant 移除 Z-Wave JS

1. 从 Z-Wave 网络中移除设备。
   • 对加入您网络的每个设备执行此操作，使其不再与适配器配对。
   • 您不能将设备添加到新适配器，而它仍与旧适配器配对。
   • 或者，您可以将每个设备恢复出厂设置。请参阅设备手册了解如何操作。
     • 这通常涉及在家庭中找到设备并按下按钮。
2. 移除 Z-Wave 集成。
   • 转到 设置 > 设备与服务 并选择集成卡片。
   • 在集成条目旁边，选择三点 菜单。
   • 选择 删除。
3. 如果未自动删除，请移除 Z-Wave JS 应用程序。
   • 转到 设置 > 应用程序 > Z-Wave JS。
   • 选择 卸载。
   • 决定是否也删除与应用程序相关的数据或保留它。
4. 完成。Z-Wave JS 现在已从您的 Home Assistant 服务器中完全移除。
   • 您现在可以在新服务器上使用您的 Z-Wave 设备和适配器。