APC UPS Daemon

    APC UPS Daemon 集成用于在 APC 设备上配置网络信息服务器（apcupsd）时与 APC 的 UPS 设备集成。使用案例：当在 Home Assistant 中设置通知集成时，您可以发送通知。例如，当 UPS 切换到电池供电时，或当电池电量下降时。您还可以使用它来跟踪 UPS 负载。

    支持的设备

    通常，apcupsd 支持的任何设备也受此集成支持。这包括大多数 APC UPS 型号，如 Smart-UPS 型号和简单信号型号（如 Back-UPS 型号）。

    前提条件

    1. 安装 apcupsd。

      首先，在连接到 UPS 的机器上安装 apcupsd。它适用于 Linux、macOS、Windows、BSD、Solaris 等。 您通常可以通过操作系统的包管理器安装它。

    2. 配置 apcupsd 以进行网络访问。

      • 打开 apcupsd.conf 文件（通常在 /etc/apcupsd/ 中找到），确保它设置为监听网络连接。
      • 查找以下行：NISIP 0.0.0.0 和 NISPORT 3551。
      • 此设置允许它在端口 3551 上接受所有网络接口上的连接。
      • 如果您愿意，可以将其设置为 Home Assistant 可以访问的特定 IP 地址和端口。

    3. 启动 apcupsd 服务。

    配置

    此集成可通过 UI 配置。前往 设置 > 设备与服务 添加。

    Host:
    description: "上面配置的 APC UPS Daemon 的 IP 地址。"
Port:
    description: "上面配置的 APC UPS Daemon 的端口。"

    支持的功能

    实体

    APC UPS Daemon 集成提供以下实体。

    二值传感器

    • 在线状态
      • 描述：指示 UPS 是否在线，从市电线路向连接的设备供电，而不是从电池供电。
      • 适用于：所有设备

    传感器

    Note

    某些传感器默认禁用，因为它们提供的信息仅对高级用户有用。您可以在 设置 > 设备与服务 > 实体 > 要启用的传感器实体 > 高级设置 > 已启用 中手动启用它们。

    • 报警延迟

      • 描述：UPS 报警的延迟时间。
      • 适用于：所有设备

    • 电池更换日期

      • 描述：上次更换电池的日期。
      • 适用于：所有设备

    • 电池电压

      • 描述：UPS 提供的电池电压。
      • 适用于：所有设备

    • 电池电量

      • 描述：电池的充电百分比。
      • 适用于：所有设备

    • 电池供电总时间

      • 描述：自 apcupsd 启动以来电池供电的总（累计）时间（秒）。
      • 适用于：所有设备

    • 日期和时间

      • 描述：写入 STATUS 记录的时间和日期。
      • 适用于：所有设备

    • 转换高电压

      • 描述：UPS 将切换到电池供电的线路电压上限。
      • 适用于：所有设备

    • 输入电压

      • 描述：UPS 返回的当前线路电压。
      • 适用于：所有设备

    • 负载

      • 描述：UPS 估算的负载容量百分比。
      • 适用于：所有设备

    • 转换低电压

      • 描述：UPS 将切换到电池供电的线路电压下限。
      • 适用于：所有设备

    • 电池超时

      • 描述：如果电池供电时间超过此值，apcupsd 将关闭您的系统。值为零则禁用此功能。值在配置文件 (TIMEOUT) 中设置。
      • 适用于：所有设备

    • 电池关机阈值

      • 描述：如果电池充电百分比 (BCHARGE) 低于此值，apcupsd 将关闭您的系统。值在配置文件 (BATTERYLEVEL) 中设置。
      • 适用于：所有设备

    • 关机时间

      • 描述：如果剩余运行时间等于或低于此点，apcupsd 将关闭您的系统。值在配置文件 (MINUTES) 中设置。
      • 适用于：所有设备

    • 电池标称电压

      • 描述：标称电池电压。
      • 适用于：所有设备

    • 标称输入电压

      • 描述：UPS 配置期望的输入电压。
      • 适用于：所有设备

    • 标称输出功率

      • 描述：UPS 设计提供的最大功率（瓦特）。
      • 适用于：所有设备

    • 转换次数

      • 描述：自 apcupsd 启动以来切换到电池供电的次数。
      • 适用于：所有设备

    • 上次自检

      • 描述：UPS 执行上次自检的日期和时间。
      • 适用于：所有设备
      • 备注：只有在执行自检（自动或手动）后才会可用。

    • 自检结果

      • 描述：上次自检的结果，可能有以下值：
        • OK：自检表明电池良好
        • BT：自检因电池容量不足而失败
        • NG：自检因过载而失败
        • NO：无结果
      • 适用于：所有设备

    • 启动时间

      • 描述：apcupsd 启动的时间/日期。
      • 适用于：所有设备

    • 状态

      • 描述：UPS 的当前状态（ONLINE、CHARGING、ONBATT 等）
      • 适用于：所有设备

    • 剩余时间

      • 描述：UPS 估算的电池剩余运行时间。
      • 适用于：所有设备

    • 电池供电时间

      • 描述：当前电池供电时间（秒），或 0。
      • 适用于：所有设备

    • 模式

      • 描述：apcupsd 运行的模式，在配置文件 (UPSMODE) 中指定
      • 适用于：所有设备

    • 从电池转换

      • 描述：上次从电池转换的时间和日期。
      • 适用于：所有设备

    • 转换到电池

      • 描述：上次转换到电池的时间和日期。
      • 适用于：所有设备
      • 备注：此实体仅在发生转换到电池事件后才可用。

    • 电池状态

      • 描述：电池的状态。
      • 适用于：Back-UPS Pro 和 Smart-UPS

    • 线路频率

      • 描述：UPS 给出的线路频率（赫兹）。
      • 适用于：Back-UPS Pro 和 Smart-UPS

    • 负载视在功率

      • 描述："视在负载"条件，指示基于电压和电流计算的 UPS 负载。这是衡量 UPS 向连接设备供电量的指标，通常以其容量的百分比报告。
      • 适用于：Back-UPS Pro 和 Smart-UPS

    • 输出电压

      • 描述：UPS 向您的设备供电的电压
      • 适用于：Back-UPS Pro 和 Smart-UPS

    • 坏电池数

      • 描述：坏电池组的数量。
      • 适用于：Smart-UPS

    • DIP 开关设置

      • 描述：具有 DIP 开关的 UPS 上的当前 DIP 开关设置。
      • 适用于：Smart-UPS

    • 低电量信号

      • 描述：UPS 发送低电量信号的剩余运行时间阈值。此时 apcupsd 将强制立即紧急关机。
      • 适用于：Smart-UPS

    • 关机延迟

      • 描述：UPS 在收到来自 apcupsd 的断电命令后，在关闭您的设备之前给予的宽限延迟。
      • 适用于：Smart-UPS

    • 唤醒延迟

      • 描述：在断电条件后恢复供电时，UPS 在恢复向您的设备供电之前等待的时间。
      • 适用于：Smart-UPS

    • 外部电池数

      • 描述：用户定义的外部电池数量。正确的数字有助于 UPS 更准确地计算剩余运行时间。
      • 适用于：Smart-UPS

    • 内部温度

      • 描述：UPS 提供的内部 UPS 温度。
      • 适用于：Smart-UPS

    • 输入电压状态

      • 描述：输入线路电压状态。"OK" 表示正常运行。
      • 适用于：Smart-UPS

    • 主设备更新

      • 描述：主设备上次向设备发送更新的时间。
      • 适用于：Smart-UPS

    • 输入电压最高值

      • 描述：自 UPS 启动以来报告的最大线路电压。
      • 适用于：Smart-UPS

    • 输入电压最低值

      • 描述：自 UPS 启动以来返回的最小线路电压。
      • 适用于：Smart-UPS

    • 标称输出电压

      • 描述：UPS 在电池供电时尝试提供的输出电压。
      • 适用于：Smart-UPS

    • 标称视在功率

      • 描述：额定的视在功率容量。
      • 适用于：Smart-UPS

    • 输出电流

      • 描述：UPS 向连接设备提供的输出电流
      • 适用于：Smart-UPS

    • 恢复要求

      • 描述：在断电条件后，电池必须具有的充电百分比，UPS 才会恢复向您的设备供电。
      • 适用于：Smart-UPS

    • 自检间隔

      • 描述：自动自检之间的间隔（小时）。
      • 适用于：Smart-UPS

    • 从电池转换

      • 描述：自 apcupsd 启动以来上次从电池转换的日期和时间。
      • 适用于：Smart-UPS

    • 环境湿度

      • 描述：UPS 测量的湿度。
      • 适用于：带有可选配件（如温度/湿度传感器或 SNMP 网络卡）的 Smart-UPS

    • 环境温度

      • 描述：UPS 测量的环境温度。
      • 适用于：带有可选配件（如温度/湿度传感器或 SNMP 网络卡）的 Smart-UPS

    • 状态数据

      • 描述：标题记录，指示 STATUS 格式修订级别、APC 语句后面的记录数以及记录后面的字节数。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 型号

      • 描述：旧的 APC 型号识别代码。
      • 适用于：Smart-UPS
      • 备注：默认禁用，供高级用户使用。

    • 电缆类型

      • 描述：配置文件 (UPSCABLE) 中指定的电缆。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 状态日期

      • 描述：上次从 UPS 获取信息的日期和时间。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 驱动程序

      • 描述：用于与 UPS 通信的驱动程序。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 固件版本

      • 描述：UPS 报告的固件修订号。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 主机名

      • 描述：收集 UPS 数据的机器名称。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 上次转换

      • 描述：上次转换到电池的原因。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 制造日期

      • 描述：UPS 制造的日期。
      • 适用于：Smart-UPS
      • 备注：默认禁用，供高级用户使用。

    • 型号

      • 描述：从 UPS 信息派生的 UPS 型号。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 寄存器 1 故障

      • 描述：来自 UPS 故障寄存器 1 的值。
      • 适用于：Smart-UPS
      • 备注：默认禁用，供高级用户使用。

    • 寄存器 2 故障

      • 描述：来自 UPS 故障寄存器 2 的值。
      • 适用于：Smart-UPS
      • 备注：默认禁用，供高级用户使用。

    • 寄存器 3 故障

      • 描述：来自 UPS 故障寄存器 3 的值。
      • 适用于：Smart-UPS
      • 备注：默认禁用，供高级用户使用。

    • 灵敏度

      • 描述：UPS 对线路电压波动的灵敏度级别。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 序列号

      • 描述：UPS 序列号。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 状态标志

      • 描述：状态标志。英文版本由 STATUS 给出。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 名称

      • 描述：存储在 EEPROM 或配置文件 UPSNAME 指令中的 UPS 名称。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    • 守护程序信息

      • 描述：apcupsd 版本号、构建日期和平台。
      • 适用于：所有设备
      • 备注：默认禁用，供高级用户使用。

    示例

    当 UPS 负载过高时发送推送通知

    alias: "APC UPS 负载过高通知"
description: "当 APC UPS 负载过高时通知"
mode: single
triggers:
  - trigger: numeric_state
    entity_id:
      - sensor.apc_ups_load
    above: 80
conditions: []
actions:
  - action: notify.notify
    data:
      message: "APC UPS 负载过高：{{ states('sensor.apc_ups_load') }}%"

    数据更新

    默认情况下，集成每 60 秒从您的 APC UPS Daemon polls 数据一次。

    已知限制

    此集成不允许您控制 UPS。例如，您无法运行自检。要运行自检，请使用 apcupsd 提供的 apctest 命令。

    故障排除

    连接失败

    如果您在设置集成时收到 连接失败 错误（和/或 Home Assistant 日志中出现 ConnectionRefusedError: Connection refused 错误），这意味着 Home Assistant 无法连接到 APC UPS 守护程序。请检查 apcupsd 配置文件中的 NISIP/NISPORT 是否正确配置。此外，尝试在主机上运行 apcaccess 以查看守护程序是否正常工作。

    某些实体不再提供

    如果 Home Assistant 重启后某些实体缺失，很可能是因为它们表示仅在特定 UPS 事件（例如切换到电池）后才会出现的事件数据。这些实体会被 APC UPS Daemon 重启时清除，直到相应事件再次发生才会重新出现。

    移除集成

    此集成遵循标准集成移除流程。无需额外步骤。

    To remove an integration instance from Home Assistant

    1. Go to Settings > Devices & services and select the integration card.
    2. From the list of devices, select the integration instance you want to remove.
    3. Next to the entry, select the three-dot menu. Then, select Delete.