#UniFi Protect

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

权限：下面关于可用于 Home Assistant 实例的功能说明，默认假设你对每台设备都拥有完整写权限。如果你使用的用户对某些设备权限受限，那么你会看到更少的实体，并且在很多情况下，获得的是只读传感器，而不是可编辑的 switch/select/number 实体。

智能检测：以下摄像头支持智能检测：

• 所有 “AI” 系列摄像头，包括 AI 360 和 AI Bullet。
• 所有 “G4” 系列摄像头，包括 G4 Doorbell、G4 Bullet、G4 Pro 和 G4 Instant。

G3 系列摄像头_不支持_智能检测。

::: 每台 UniFi Protect 摄像头在 Home Assistant 中都会对应一个设备，并具有以下内容：

• Camera - 每个摄像头的每个通道及 RTSP(S) 组合都会创建一个摄像头实体（最多 7 个）。默认仅启用分辨率最高的 RTSPS 摄像头实体。
  • 如果你的摄像头是 G4 Doorbell Pro，还会额外为包裹摄像头添加一个摄像头实体。无论该通道是否启用了 RTSPS，包裹摄像头实体都_不支持_流媒体播放。这是因为包裹摄像头的 FPS 很低，无法兼容 HLS 流媒体。
• Media Player - 如果摄像头带有扬声器，你将获得一个媒体播放器实体，可将音频播放到摄像头扬声器。任何可被 FFmpeg 播放的音频文件 URI 都可播放到扬声器上，包括通过 TTS Say 操作。
• Privacy Mode - 如果摄像头支持隐私遮罩，则会提供一个配置开关来切换“隐私模式”，该模式会禁用录像、麦克风，并在整个画面上覆盖黑色隐私区域。
• Sensors - 传感器包括 Is Dark、Motion Detected、检测对象传感器（如果摄像头支持智能检测）以及 Doorbell Chime（如果摄像头带有铃声器）。还会添加多个诊断传感器，包括运行时间、网络连接统计和存储统计。门铃设备还会提供 Voltage 传感器，用于排查电气问题。
  • 摄像头支持的每一种智能检测都会对应一个检测对象传感器，另有一个组合传感器用于表示是否检测到_任意_对象。
• Device Configuration - 摄像头会根据其支持的功能提供多种配置控件。目前包括：
  • 用于 Chime Type、Zoom Level、Microphone Sensitivity 和 WDR Level 的滑块
  • 用于 Overlay Information、Smart Detections 类型、Status Light、HDR、High FPS 模式、System Sounds 的开关
  • 门铃 LCD Screen 的文本和选择配置，可用于设置自定义消息或使用预设消息
• Button - 每台摄像头设备都会添加一个默认禁用的按钮实体，可用于重启摄像头设备。

#PTZ 摄像头

如果你的摄像头支持 PTZ，还可使用以下附加实体和功能：

• PTZ patrol - 一个 select 实体，可让你启动或停止在 UniFi Protect 中配置的巡航。其状态会反映当前激活的巡航。选择 Stopped 可停止当前巡航。
• PTZ presets - 使用 PTZ 转到预设位操作（unifiprotect.ptz_goto_preset）可将 PTZ 摄像头移动到已保存的预设位置，包括 home 位置。预设位必须先在 UniFi Protect 应用中配置。

#UniFi Protect 泛光灯

每个 UniFi Protect 泛光灯在 Home Assistant 中都会对应一个设备，并具有以下内容：

• Light - 每个泛光灯设备都会添加一个灯光实体，可用于开关灯光并调节亮度。
• Sensors - 会提供来自泛光灯设备数据的传感器，包括 Is Dark 和 Motion Detected。
• Device Configuration - 泛光灯会提供 PIR 运动灵敏度、检测到运动后的自动关闭时长，以及 Status Light 开关等配置控件。
• Button - 每个泛光灯设备都会添加一个默认禁用的按钮实体，可用于重启泛光灯设备。

#UniFi Protect 智能传感器

UniFi Protect 智能传感器与普通传感器略有不同。它们属于多合一传感器，可作为接触传感器（门/窗）、运动探测器、光照传感器、湿度传感器、温度传感器、警报声音传感器和/或漏水探测器。每项传感功能都可动态启用或禁用。被禁用的传感器会标记为 unavailable。

• Sensors - 智能传感器设备的每项主要功能都会提供相应传感器：
  • Contact - 如果安装类型设置为 Door、Window 或 Garage，则会提供接触传感器。
  • Motion Detection - 如果安装类型不是 Leak 且已启用运动检测，则会提供运动检测传感器。
  • Light Level - 如果安装类型不是 Leak 且已启用光照传感器，则会提供光照传感器。
  • Humidity - 如果安装类型不是 Leak 且已启用湿度传感器，则会提供湿度传感器。
  • Temperature - 如果安装类型不是 Leak 且已启用温度传感器，则会提供温度传感器。
  • Alarm Sound - 如果安装类型不是 Leak 且已启用警报声音传感器，则会提供警报传感器。Alarm Sound 传感器的值可以是 none、smoke 和 co。随着 UniFi Protect 支持识别更多警报，后续可能会自动增加更多取值。
  • Tamper - 用于检测防拆的二进制传感器。
• Device Configuration - 智能传感器会提供 Status Light、启用/禁用所有主要传感器、选择 Paired Camera 以及更改安装类型等配置控件。
• Button - 提供一个用于清除防拆状态的按钮实体，以及一个默认禁用的设备重启按钮。

#防拆传感器

防拆传感器一旦触发，会持续保持激活状态，直到手动清除。可使用一个按钮实体来清除防拆状态。

#UniFi Protect 查看器

每个 UniFi Protect 查看器在 Home Assistant 中都会对应一个设备，并具有以下内容：

• Liveview Select - 每个查看器设备都会添加一个 select 控件，用于选择查看器上显示的 liveview。
• Button - 每个查看器设备都会添加一个默认禁用的按钮实体，可用于重启查看器设备。

#UniFi Protect DoorLock

每个 UniFi Protect 门锁在 Home Assistant 中都会对应一个设备，并具有以下内容：

• Lock - 会添加一个锁控件，用于锁定和解锁门锁设备。
• Device Configuration - 门锁会提供 Auto-Lock Timeout、选择 Paired Camera 以及 Status Light 开关等配置控件。
• Button - 每个门锁设备都会添加一个默认禁用的按钮实体，可用于重启门锁设备。

#UniFi Protect Smart Chime

每个 UniFi Protect 智能门铃铃声器在 Home Assistant 中都会对应一个设备，并具有以下内容：

• Button - 每个智能铃声器设备都会提供一个按钮用于手动触发铃声，另外还会添加一个默认禁用的按钮用于重启设备。
• Device Configuration - 智能铃声器会提供一个音量滑块用于调节铃声音量，以及一个记录上次响铃时间的传感器。

#NVR

你的主 UniFi Protect NVR 设备还会提供多个诊断传感器，可用于跟踪 UniFi Protect 系统状态：

• Disk Health：NVR 中安装的每块磁盘都会有一个磁盘健康传感器。这些是简单的好/坏状态传感器，其顺序不保证与 UniFi OS 中显示的顺序一致。不过状态属性中会提供磁盘型号，以帮助你对应到具体磁盘。
• Utilization and Storage Sensors：还会添加多个传感器，用于显示运行时间、硬件利用率以及磁盘上视频分布等细节。

#媒体源

系统会为你的 UniFi Protect 摄像头提供媒体源，以便获取视频片段和事件缩略图。

#媒体浏览器

该媒体源分为 5 个文件夹/层级：

1. NVR Console Selector - 仅当你拥有多个 Protect NVR Console 时才会出现。可用于选择要查看事件的 NVR Console。
2. Camera Selector - 可选择查看所有摄像头的事件，或仅查看某个特定摄像头的事件。
3. Event Selector - 可选择查看所有事件，或仅查看某一特定事件类型。
4. Time Selector - 按指定时间范围筛选事件：
   • 最近 24 小时
   • 最近 7 天
   • 最近 30 天
   • 按录制开始后的月份查看 - 选择某个月后，可查看整个月或某个具体日期
5. Event Selector - 选择要播放的具体事件

由于媒体浏览器不支持分页或过滤，所有事件都必须加载到内存中。因此，默认一次最多加载 10,000 条事件。如果事件数量被截断，界面中会显示为 10000 (TRUNCATED)。你可以在配置条目选项中调高或调低可加载事件数的上限。

#媒体标识符

以下是可用于解析媒体的标识符。由于事件不一定映射到某个 Home Assistant 实体，因此这里所有 ID 都指 UniFi Protect 的 ID，而不是 Home Assistant 的 ID。

#操作

#操作：添加门铃文本

unifiprotect.add_doorbell_text 操作用于为门铃添加新的自定义消息。

#操作：移除门铃文本

unifiprotect.remove_doorbell_text 操作用于移除门铃现有的自定义消息。

#操作：设置铃声器配对门铃

unifiprotect.set_chime_paired_doorbells 操作用于设置与智能铃声器配对的门铃。

#操作：移除隐私区域

unifiprotect.remove_privacy_zone 操作用于从摄像头中移除一个隐私区域。

#操作：PTZ 转到预设位

unifiprotect.ptz_goto_preset 操作用于将 PTZ 摄像头移动到已保存的预设位置。

#用法示例

action: unifiprotect.ptz_goto_preset
data:
  device_id: your_device_id_here
  preset: "Home"

#操作：获取用户钥匙串信息

unifiprotect.get_user_keyring_info 操作用于获取某个 UniFi Protect 实例的钥匙串信息。

#用法示例

action: unifiprotect.get_user_keyring_info
data:
  device_id: your_device_id_here

响应中会包含一个用户列表，其中包括用户全名、状态以及关联的密钥（指纹或 NFC）。

#响应示例

users:
  - full_name: User One
    user_status: ACTIVE
    ulp_id: d23e27e0-a32a-41e5-9424-be646330c2d5
    keys: []
  - full_name: User Two
    user_status: ACTIVE
    ulp_id: a243ffdb-3ab2-4186-b2fe-0b53ccb29f24
    keys:
      - key_type: nfc
        nfc_id: ABCDEF12
      - key_type: fingerprint
        fingerprint_id: "1"

#视图

该集成提供了四个代理视图，用于通过 Home Assistant 实例代理媒体内容。这样你就可以在 Home Assistant 环境中访问缩略图和视频片段，而无需暴露 UniFi Protect NVR Console。与媒体标识符一样，这里的所有 ID 都是 UniFi Protect ID，因为根据你的集成配置方式，它们未必能映射到具体的 Home Assistant 实体。

这些 URL 很适合用于发送通知。如果在自动化或 notify 操作 中使用，Home Assistant 会自动为这些 URL 签名，使其可安全用于外部访问。

四个代理 API 端点 URL：

/api/unifiprotect/thumbnail/{nvr_id}/{event_id}

• 代理来自 UniFi Protect 的 JPEG 事件缩略图。

/api/unifiprotect/video/{nvr_id}/{event_id}

• 代理来自 UniFi Protect 的指定事件 MP4 视频片段。要获取视频，该事件必须已经结束；如果事件仍在进行中，请使用下方定义的摄像头端点。

/api/unifiprotect/snapshot/{nvr_id}/{camera_id}/{timestamp}

• 代理来自 UniFi Protect 的指定摄像头在给定时间戳下的 JPEG 图像。timestamp 必须为 ISO 8601 格式。

/api/unifiprotect/video/{nvr_id}/{camera_id}/{start}/{end}

• 代理来自 UniFi Protect 的指定摄像头 MP4 视频片段。start 和 end 必须为 ISO 8601 格式。

nvr_id 可以是你的 NVR 的 UniFi Protect ID，也可以是 UniFi Protect 集成的配置条目 ID。camera_id 可以是摄像头的 UniFi Protect ID，也可以是由 UniFi Protect 集成提供、且可反向解析为某台 UniFi Protect 摄像头的任意实体 ID（例如某个检测对象传感器的实体 ID）。

查找 nvr_id、camera_id、start 和 end 的最简单方法，是在媒体浏览器中查看 UniFi Protect 的某个视频。如果你在浏览器新标签页中打开视频，就能在 URL 中看到这些值。start 时间通常接近传感器开始检测到运动时该事件的 last_changed 时间戳；end 时间则接近传感器停止检测到运动时该事件的 last_changed 时间戳。类似地，如需查看图片的 event_id，可前往 设置 > 开发者工具 > 状态，找到传感器开始检测运动时对应的事件。

#带缩略图的通知自动化示例

此示例会在检测到运动时发送一条带摄像头缩略图的通知。短暂延迟可确保在通知发送前缩略图已可用。

alias: "Motion detection with image"
description: "当检测到运动时发送带有相机快照的通知。"
triggers:
  - entity_id: binary_sensor.g4_instant_motion # Replace with your camera entity
    trigger: state
    from: off
    to: on
actions:
  - delay:
      seconds: 2
  - data:
      message: "Motion detected"
      data:
        image: >-
          /api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.to_state.attributes.event_id }}
    action: notify.mobile_app_your_device # Replace with your notification target

#带视频的通知自动化示例

alias: "Security: Camera Motion Notification"
description: "Sends a notification with video upon motion detection."
triggers:
  - entity_id:
      - binary_sensor.g5_bullet_motion # Replace with your camera entity
    trigger: state
    from: "on"
    to: "off"
actions:
  - data:
      message: "Motion detected at Camera XXX"
      data:
        image: >-
          /api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}
        video: >-
          /api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}
    action: notify.mobile_app_your_device # Replace with your notification target
mode: single
max_exceeded: silent

在发送通知前，等待运动传感器从 on 变为 off 非常重要。这样可确保事件已经结束且视频可访问；否则你拿到的可能不是视频链接，而是错误。

:::note iOS Companion App 不支持通过本地 URL 附加视频。图片可使用相对路径，但视频附件需要使用外部可访问的 URL，或采用其他传递方式。

即使未检测到车牌，车辆检测事件也会被触发。只有当车牌识别成功识别出车牌时，license_plate 属性才会出现。3 秒延迟可确保如果 LPR 数据可用，它会被包含在事件中。

::: :::warning 车牌识别可能会被多种来源触发，包括包含车牌图像的图片或印刷材料。在基于车牌检测创建自动化时务必谨慎，尤其是打开车库门或解锁大门等安全敏感操作。建议加入额外验证方式或时间限制，以防止误触发。请自行承担使用风险。