#Universal Devices ISY/IoX

ISY 是一款家庭自动化控制器，能够控制连接到 Universal Devices, Inc. 支持硬件上的 Insteon、X10、Z-Wave 以及 Zigbee/Matter 设备。

此集成支持传统的 ISY994 硬件系列，也支持当前的 ISY-on-Anything（IoX）硬件，比如 eisy 或 Polisy 设备。

Home Assistant 目前支持以下平台：

• Binary sensor
• Button
• Climate
• Cover
• Light
• Fan
• Lock
• Number
• Select
• Sensor
• Switch

Home Assistant 可以与控制器上配置的任何二进制传感器、卷帘、风扇、灯光、锁、传感器和开关通信。通过控制器上的程序，还可以创建自定义二进制传感器、卷帘、风扇、锁和开关。每个设备以及 ISY 集线器本身也都包含一个 Query 按钮，用于查询设备。

你还可以通过创建的按钮执行 ISY Networking Module Resources。

配置好 ISY 控制器后，它会自动导入它能找到的所有二进制传感器、卷帘、风扇、灯光、锁、传感器和开关。

#配置选项

你可以使用多个选项进一步自定义从 ISY 控制器导入的内容，以及实体的行为。

• Sensor String：用于识别哪些设备应被视为传感器而不是灯光或开关。如果设备名称或文件夹中包含这个字符串，Home Assistant 会将其视为传感器或二进制传感器（如果设备只有开/关或 true/false 状态）。只有当节点未被 Home Assistant 自动识别为传感器时才需要使用它。Insteon 门磁、窗磁、运动和漏水传感器通常都会被自动检测到
• Variable Sensor String：用于识别哪些 Integer 或 State Variables 应默认启用为 number 实体。如果设备名称中包含这个字符串，Home Assistant 会将其视为传感器。默认值为 "HA."
• Ignore String：名称（或文件夹路径）中包含该字符串的任何设备都会被 Home Assistant 忽略。它们不会成为实体，也不会触发 control_events。默认值为 "{IGNORE ME}"
• Restore Light State：如果禁用（默认行为），从 Home Assistant 打开灯光且未设置 brightness 参数时，灯会使用物理设备中设置的 on_level 亮度。例如，在 Insteon 设备上，这会与按下实体开关时的亮度相同。如果启用该设置，从 Home Assistant 打开的灯会恢复到最后已知亮度值。如有需要，on_level 和 last_brightness 都可作为属性用于进一步自定义

#传感器

Insteon 门/窗传感器在 Home Assistant 中会显示为一个二进制传感器，而不是像 ISY 管理控制台中那样显示为两个独立设备。请注意，在“Two Nodes”模式下，传感器会一直显示 UNKNOWN，直到自上次 Home Assistant 重启以来第一次状态变化。如果你不使用由门传感器直接控制的 Insteon 场景，可能更适合在 ISY 管理面板中将传感器设置为“One Node”模式。

每个 Insteon 漏水传感器在 Home Assistant 中同样会显示为一个二进制传感器，而不是 ISY 管理控制台中的两个节点。设备名称基于 ISY 中父节点的名称，通常是名称以 -Dry 结尾的那个节点。这可能会让人困惑，因为在 Home Assistant 中，“On” 表示潮湿。你可以在 Home Assistant 中重命名该节点，使其更清晰。请参阅配置中的自定义部分。

如果你的漏水或门/窗传感器支持心跳，Home Assistant 中会新增一个 binary_sensor 设备来表示电池状态。只要每日心跳正常，该传感器就会保持为 “Off”。如果漏掉一次心跳，传感器就会变为 “On”。该设备名称基于 ISY 中的心跳节点名称。

#ISY/IoX Variables

ISY 中的 Integer 和 State Variables 会作为 number 实体导入。你可以通过设置“Variable Sensor String”配置选项，并在 ISY 管理控制台中把它作为变量名的一部分（例如，选项中用 HA.，在 ISY 中变量名使用 HA.Variable Name），来选择哪些变量默认启用。你也可以在 Home Assistant 中从 ISY Variables 设备手动启用所需实体。

#处理 Insteon 或其他 ISY 控制事件

对于 ISY 设备网络中的每一个“control”事件，都会发出一个 Home Assistant isy994_control 事件（前提是该设备未在 Home Assistant 中被忽略或禁用）。这样你就可以编写自动化，根据 Insteon 按钮按下等事件触发操作。你也可以基于 Insteon/Zigbee/Z-Wave 的独特事件触发，比如双击、长按等。

automation:
  - alias: "turn off living room on double tap lightswitch"
    triggers:
      - trigger: event
        event_type: isy994_control
        event_data:
          entity_id: light.lr_track_lights_front
          control: "DFON"
          value: 255
          formatted: "On"
          uom: "100"
          prec: "0"
    actions:
      - action: light.turn_off
        target:
          entity_id: light.lr_track_lights_rear

所有 isy994_control 事件的 event_data 中都会包含 entity_id 和 control 参数。你需要参考 ISY 文档来查看全部可能的 control 类型，以下是一些常见值：

• DON：On 按钮
• DOF：Off 按钮
• DFON：Fast On，通常来自双击 On 按钮
• DFOF：Fast Off，通常来自双击 Off 按钮
• FDUP：Fade Up，通常是在按住 On 按钮时
• FDDOWN：Fade Down，通常是在按住 Off 按钮时
• FDSTOP：Fade Stop，在释放长按按钮时
• BRT：Brighten，来自会发送单条命令以略微调亮灯光的控制器
• DIM：Dim，来自会发送单条命令以略微调暗灯光的控制器

#Insteon 场景与 Keypad/Remote 按钮

所有在 ISY 管理控制台中配置的 Insteon 场景都会在 Home Assistant 中显示为 switch，因为它们不像 Home Assistant 的 light 集成那样支持调光或设置特定亮度。

Insteon 次级 Keypad 按钮和 Remote 按钮也会被添加到 Home Assistant，以支持在自动化中使用控制事件。由于这些设备不能被直接控制（不能开关），它们会被添加为 sensors；其状态是它们最近一次发送的 ON 级别命令，范围从 0（关闭）到 255（100% 开启）。注意：这些设备在 ISY 重启后，第一次使用前可能会报告不正确的状态。次级 Keypad 按钮可以通过 ISY 场景打开或关闭（详见 ISY 文档）。

#Insteon 设备配置支持

如果设备支持，Insteon 设备会包含用于设置设备 On Level、Ramp Rate 和 Backlight Level 的实体，以及用于 Beep 和 Query 操作的 button 实体。注意：Backlight Level 无法从设备读取，因此使用的是假定状态。如果背光亮度是从 Home Assistant 改变的，则 Home Assistant 中的当前状态有效；如果在 Home Assistant 运行期间通过 ISY 管理控制台或 REST 命令更改，它也会更新。其他配置变更仍需使用 ISY 管理控制台。

#操作

加载完成后，将以 isy994. 前缀公开以下操作，以便对 ISY 及其连接的设备进行高级控制：

• 面向所有连接到 Home Assistant 的实体的操作：send_node_command、send_raw_node_command
• ISY Z-Wave 节点操作：get_zwave_parameter、set_zwave_parameter、set_zwave_lock_user_code、delete_zwave_lock_user_code
• 通用 ISY 操作：send_program_command

#操作 isy994.send_node_command

使用 Home Assistant 实体 ID 向 ISY 设备发送命令。有效命令包括：beep、brighten、dim、disable、enable、fade_down、fade_stop、fade_up、fast_off、fast_on 和 query。

#操作 isy994.send_raw_node_command

使用 Home Assistant 实体 ID 向节点发送“原始” ISY REST 设备命令（例如 DON、DOF）。这对那些在 Home Assistant 中尚未完全支持的设备很有用，比如许多 NodeServer 节点的控制项。有效命令详情请参阅 ISY（或 PyISY Python 模块）文档。

#操作 isy994.get_zwave_parameter

通过 ISY 请求 Z-Wave 设备参数。参数值会作为实体的额外状态属性返回，属性名为 ZW#，其中 # 是参数编号。

#操作 isy994.set_zwave_parameter

通过 ISY 更新 Z-Wave 设备参数。参数值也会作为实体的额外状态属性返回，属性名为 ZW#，其中 # 是参数编号。

#操作 isy994.set_zwave_lock_user_code

通过 ISY 设置 Z-Wave 门锁用户密码。

#操作 isy994.delete_zwave_lock_user_code

通过 ISY 删除 Z-Wave 门锁用户密码。

#操作 isy994.rename_node

重命名 ISY994 上的节点或组（场景）。注意：这不会自动更改 Home Assistant 中对应的实体名称或实体 ID。只有在重新加载集成或重启 Home Assistant 后，并且你尚未在 Home Assistant 中自定义名称的前提下，实体名称和 ID 才会更新。

#操作 isy994.send_program_command

发送命令来控制 ISY 程序或文件夹。有效命令包括 run、run_then、run_else、stop、enable、disable、enable_run_at_startup 和 disable_run_at_startup。

#使用 ISY 程序创建自定义设备

通过控制器管理控制台中的 Programs 选项卡，你可以创建会原生显示在 Home Assistant 中的自定义设备。Home Assistant 会扫描以下文件夹，并将设备构建到对应域中：

My Programs
├── HA.binary_sensor
|   ├── Movement In House
|   |   └── status
|   └── Garage Open
|   |   └── status
├── HA.cover
|   ├── Left Garage Door
|   |   ├── actions
|   |   └── status
|   ├── Living Room Blinds
|   |   ├── actions
|   |   └── status
├── HA.fan
|   ├── Desk Fan
|   |   ├── actions
|   |   └── status
|   ├── Living Room Fan
|   |   ├── actions
|   |   └── status
├── HA.lock
|   ├── Front Door
|   |   ├── actions
|   |   └── status
|   ├── Back Door
|   |   ├── actions
|   |   └── status
├── HA.switch
|   ├── Dining Lights
|   |   ├── actions
|   |   └── status
|   ├── Sleep Mode
|   |   ├── actions
|   |   └── status

你可以通过在以下任意根目录下创建一个以设备名称命名的目录来创建设备：

• HA.binary_sensor 将创建一个二进制传感器（可参阅自定义设备设置传感器类别）
• HA.cover 将创建一个卷帘
• HA.fan 将创建一个风扇
• HA.lock 将创建一个锁
• HA.switch 将创建一个开关

在程序设备目录下必须有一个名为 status 的程序。除 binary_sensor 外，所有程序设备还必须有一个名为 actions 的程序。设备目录中的其他程序都会被忽略。

status 程序要求你创建一个可自定义名称的 state variable。请注意，必须使用 state variable，而不是 integer variable。这个变量将存储新设备的实际状态，并由 action 程序更新。

设备目录中 status 程序的 IF 子句用于表示设备状态：

• binary_sensor：如果子句返回 true，则为 on，否则为 off
• cover：如果子句返回 true，则为 closed，否则为 open
• fan：如果子句返回 true，则为 on，否则为 off
• lock：如果子句返回 true，则为 locked，否则为 unlocked
• switch：如果子句返回 true，则为 on，否则为 off

actions 程序用于指定以下设备操作应执行什么：

• cover：open_cover 操作会执行 THEN 子句，close_cover 操作会执行 ELSE 子句
• fan：turn_on 操作会执行 THEN 子句，turn_off 操作会执行 ELSE 子句
• lock：lock 操作会执行 THEN 子句，unlock 操作会执行 ELSE 子句
• switch：turn_on 操作会执行 THEN 子句，turn_off 操作会执行 ELSE 子句

上面的示例程序展示了如何使用 ISY 控制器从 Home Assistant 控制传统 X10 设备。