diff --git a/source/_integrations/unifiprotect.markdown b/source/_integrations/unifiprotect.markdown index decff7d3d81..c76aaf7ad83 100644 --- a/source/_integrations/unifiprotect.markdown +++ b/source/_integrations/unifiprotect.markdown @@ -280,6 +280,32 @@ Three URLs for proxy API endpoints: The easiest way to find the `nvr_id`, `camera_id`, `start`, and `end` times is by viewing one of the videos from UniFi Protect in the Media browser. If you open the video in a new browser tab, you will see all these values in the URL. The `start` time is close to the last_changed timestamp of the event when the sensor started detecting motion. The `end` time is close to the last_changed timestamp of the event when the sensor stopped detecting motion. Similarly, to see the `event_id` of the image, go to {% my developer_states title="**Developer Tools** > **States**" %} and find the event when the sensor started detecting motion. +### Example Notification Automation with Video + +```yaml +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: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}{% endraw %} + video: >- + {% raw %}/api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}{% endraw %} + action: notify.mobile_app_your_device # Replace with your notification target +mode: single +max_exceeded: silent +``` + +Waiting for the motion sensor to change from `on` to `off` before sending the notification is essential. Waiting ensures that the event has ended and the video is accessible; otherwise, you may get an error instead of the video link. + ## Event Entities Support The UniFi Protect integration provides support for various event types triggered by connected devices. Below are the descriptions for each supported event type: @@ -292,6 +318,29 @@ The UniFi Protect integration provides support for various event types triggered - **event_id**: A unique ID that identifies the doorbell event. - **Description**: This event is triggered when someone rings the doorbell. It provides an `event_id`, which can be used to fetch related media, such as a thumbnail of the event. For instance, you can use `event.g4_doorbell_pro_doorbell` to get the thumbnail image when a ring occurs. +#### Example G4 Doorbell Ring Triggered Automation + +```yaml +alias: G4 Doorbell Ring Triggered Automation +description: Automation that triggers when the G4 Doorbell Pro rings +triggers: + - event_type: state_changed + event_data: + entity_id: event.g4_doorbell_pro_poe_doorbell # Replace with your doorbell entity + trigger: event +conditions: + - condition: template + value_template: | + {% raw %}{{ 'ring' in trigger.event.data.new_state.attributes.event_types }}{% endraw %} +actions: + - data: + message: Someone is at the door! + title: Doorbell Notification + action: notify.mobile_app_your_device # Replace with your notification target +``` + +The condition is required to prevent the notification from being triggered by events of type 'unknown', for example, during a restart. + ### NFC Card Scanned Event - **Event Name**: NFC @@ -301,6 +350,38 @@ The UniFi Protect integration provides support for various event types triggered - **nfc_id**: The ID of the scanned NFC card. - **Description**: This event is triggered when an NFC card is scanned at a compatible device (e.g., a smart doorbell). It contains information such as the `nfc_id` of the scanned card. +#### Example G4 Doorbell NFC Scanned Automation + +```yaml +alias: G4 Doorbell NFC Scanned Automation +description: >- + Automation that triggers when a specific NFC card is scanned on the G4 + Doorbell Pro +triggers: + - event_type: state_changed + event_data: + entity_id: event.g4_doorbell_pro_poe_nfc # Replace with your doorbell entity + trigger: event +conditions: + - condition: template + value_template: > + {% raw %}{{ + trigger.event.data.new_state is not none and + trigger.event.data.new_state.attributes.event_type == 'scanned' and + trigger.event.data.new_state.attributes.nfc_id in ['ABCDEF1234', 'OTHER_ALLOWED_ID'] + }}{% endraw %} +actions: + - data: + message: >- + {% raw %}The NFC card with ID {{ trigger.event.data.new_state.attributes.nfc_id }} has been scanned at the doorbell.{% endraw %} + title: NFC Scan Notification + action: notify.mobile_app_your_device # Replace with your notification target +``` + +**Warning:** + +When processing NFC scans, always validate the scanned ID. Unknown NFC cards also trigger the scan event. Additionally, this event was developed using third-party cards, as the developer did not have access to official UniFi cards at the time. With third-party cards, the scan relies on the card's serial number. While this approach is not uncommon, it is essential to note that the card's serial number is generally not considered a secure identifier and can be duplicated relatively easily. + ### Fingerprint Identified Event - **Event Name**: Fingerprint @@ -310,6 +391,36 @@ The UniFi Protect integration provides support for various event types triggered - **ulp_id**: The fingerprint ID used to identify the person. If no fingerprint match is found, the `ulp_id` will be empty and the `event_type` will be `not_identified`. - **Description**: This event is triggered when a fingerprint is scanned by a compatible device. If the fingerprint is recognized, it provides a `ulp_id`, which represents the fingerprint ID. If the fingerprint is not recognized, the `event_type` will be set to `not_identified`, and no `ulp_id` will be provided. +#### Example G4 Doorbell Fingerprint Identified Automation + +```yaml +alias: G4 Doorbell Fingerprint Identified Automation +description: Automation that triggers when a fingerprint is successfully identified on the G4 Doorbell Pro +trigger: + - platform: event + event_type: state_changed + event_data: + entity_id: event.g4_doorbell_pro_poe_fingerprint # Replace with your doorbell entity +condition: + - condition: template + value_template: > + {% raw %}{{ + trigger.event.data.new_state is not none and + trigger.event.data.new_state.attributes.event_type == 'identified' and + (trigger.event.data.new_state.attributes.ulp_id|default('')) != '' and + trigger.event.data.new_state.attributes.ulp_id in ['ALLOWED_ID1', 'ALLOWED_ID2'] + }}{% endraw %} +action: + - service: notify.mobile_app_your_device # Replace with your notification target + data: + {% raw %}message: "Fingerprint identified with ID: {{ trigger.event.data.new_state.attributes.ulp_id }}"{% endraw %} + title: "Fingerprint Scan Notification" +``` + +**Warning:** + +Similar to NFC, an event is triggered when a fingerprint is recognized and not recognized. However, unlike NFC, at the time of implementation, no fingerprint ID is included in the event if the fingerprint is unknown. + ## Troubleshooting ### Delay in video feed