Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

unifiprotect-fingerprint-and-nfc-event-support #35892

Open
wants to merge 2 commits into
base: next
Choose a base branch
from
Open

unifiprotect-fingerprint-and-nfc-event-support #35892

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fab21ff
unifiprotect-fingerprint-and-nfc-event-support
RaHehl Nov 21, 2024
be2081c
unifiprotect moved position of event addition
RaHehl Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions source/_integrations/unifiprotect.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,36 @@ check that this is done. To check and enable the feature:

{% include integrations/config_flow.md %}

## 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:

### Doorbell Ring Event

- **Event Name**: Doorbell
- **Event Attributes**:
- **event_type**: `doorbell`
- **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.

### NFC Card Scanned Event

- **Event Name**: NFC
- **Event Attributes**:
- **event_type**: `nfc_card_scanned`
- **event_id**: A unique ID that identifies the NFC card scan event.
- **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.

### Fingerprint Identified Event

- **Event Name**: Fingerprint
- **Event Attributes**:
- **event_type**: Either `fingerprint_identified` or `fingerprint_not_identified`
- **event_id**: A unique ID that identifies the fingerprint event.
- **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 `fingerprint_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 `fingerprint_not_identified`, and no `ulp_id` will be provided.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add security considerations for fingerprint events.

Consider adding a note about security best practices when handling fingerprint-related data in automations.

 - **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 `fingerprint_not_identified`, and no `ulp_id` will be provided.
+
+{% note %}
+**Security Note**: When using fingerprint events in automations, follow security best practices:
+- Avoid logging or storing the `ulp_id` in external systems
+- Use secure methods to handle access control decisions
+- Consider implementing rate limiting for failed attempts
+{% endnote %}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### Fingerprint Identified Event
- **Event Name**: Fingerprint
- **Event Attributes**:
- **event_type**: Either `fingerprint_identified` or `fingerprint_not_identified`
- **event_id**: A unique ID that identifies the fingerprint event.
- **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 `fingerprint_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 `fingerprint_not_identified`, and no `ulp_id` will be provided.
### Fingerprint Identified Event
- **Event Name**: Fingerprint
- **Event Attributes**:
- **event_type**: Either `fingerprint_identified` or `fingerprint_not_identified`
- **event_id**: A unique ID that identifies the fingerprint event.
- **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 `fingerprint_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 `fingerprint_not_identified`, and no `ulp_id` will be provided.
{% note %}
**Security Note**: When using fingerprint events in automations, follow security best practices:
- Avoid logging or storing the `ulp_id` in external systems
- Use secure methods to handle access control decisions
- Consider implementing rate limiting for failed attempts
{% endnote %}


## Device support

All known UniFi Protect devices should be supported. Each UniFi Protect device will get a variety of entities added for
Expand Down Expand Up @@ -274,8 +304,6 @@ Two 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 the last_changed timestamp of the event when the sensor started detecting motion. The `end` time is 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.

When a Doorbell rings, there is a specific event {% term entity %} that provides the `event_id`. You can use this to get the thumbnail, for example, `event.g4_doorbell_pro_doorbell`.

## Troubleshooting

### Delay in video feed
Expand Down