add examples for UniFi Protect integration events #36029
Conversation
home-assistant
bot
added
in-progress
|
It seems that this PR is targeted against an incorrect branch. Documentation updates which apply to our current stable release should target the |
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
replaces my messed up PR #36027 |
📝 Walkthrough📝 WalkthroughWalkthroughThe changes in this pull request enhance the documentation for the UniFi Protect integration by adding example automation configurations and expanding the troubleshooting section. New YAML code snippets illustrate how to set up automations for various events, including camera motion detection, doorbell rings, NFC card scans, and fingerprint identification. Additionally, new actions related to doorbell text management and privacy zones have been introduced, along with their respective attributes. Changes
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (3)
source/_integrations/unifiprotect.markdown (3)
279-301: Enhance the notification automation exampleThe example is good but could be improved for better clarity and maintainability:
title: "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) + - binary_sensor.g5_bullet_motion # Replace with your camera's motion sensor trigger: state from: "on" to: "off" actions: - data: - message: "Motion detected at Camera XXX" + message: "Motion detected at {{ trigger.entity_id.split('.')[1] | replace('_', ' ') | title }}" 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) + service: notify.mobile_app_your_device # Replace with your notification service mode: single -max_exceeded: silent +max_exceeded: silent # Silently drop notifications if automation is triggered too frequentlyConsider adding a brief explanation of the
modeandmax_exceededsettings in a comment, as they're important for preventing notification spam.
319-338: Improve the doorbell ring automation exampleThe example is functional but could be enhanced for better clarity:
alias: G4 Doorbell Ring Triggered Automation description: Automation that triggers when the G4 Doorbell Pro rings triggers: - - event_type: state_changed + - platform: event + event_type: state_changed event_data: - entity_id: event.g4_doorbell_pro_poe_doorbell (replace with your camera) + 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 %} + {% raw %}{{ trigger.event.data.new_state is not none and 'ring' in (trigger.event.data.new_state.attributes.event_types|default([])) }}{% endraw %}The improved condition template adds null checks to prevent errors during Home Assistant restarts or when attributes are missing.
351-377: Enhance the NFC card scan automation exampleThe example is good, but the condition template could be more robust:
triggers: - - event_type: state_changed + - platform: event + event_type: state_changed event_data: - entity_id: event.g4_doorbell_pro_poe_nfc (replace with your camera) + 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.attributes.event_type == 'scanned' and - trigger.event.data.new_state.attributes.nfc_id == 'ABCDEF1234' }} (replace with your nfc_id){% endraw %} + {% 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 == 'ABCDEF1234' # Replace with your NFC card ID + }}{% endraw %}The security warning about NFC card IDs is crucial and well-placed. Consider storing the NFC card ID in a separate input_text helper for easier management.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/unifiprotect.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/unifiprotect.markdown
[uncategorized] ~303-~303: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...n. This ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
🔇 Additional comments (1)
source/_integrations/unifiprotect.markdown (1)
Line range hint 277-416: Overall documentation improvements look great!
The added examples and documentation for event entities support are well-structured and provide valuable guidance for users implementing UniFi Protect integration features. The examples cover common use cases and include important security considerations.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Outside diff range and nitpick comments (3)
source/_integrations/unifiprotect.markdown (3)
279-301: Enhance the notification automation exampleThe example could be improved for better clarity and user experience:
```yaml +alias: "Security Camera Motion Notification" +description: "Sends a notification with video clip when motion is detected on a security camera" 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" + message: > + Motion detected at {{ trigger.entity_id.replace('binary_sensor.','').replace('_motion','').title() }} + from {{ trigger.from_state.last_changed.strftime('%I:%M %p') }} + to {{ trigger.to_state.last_changed.strftime('%I:%M %p') }} data: image: >- {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id)
319-336: Enhance the doorbell ring automation exampleThe example could be improved with additional features and better notification content:
```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! + message: > + Doorbell rang at {{ trigger.event.time_fired.strftime('%I:%M %p') }} title: Doorbell Notification + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) + }}/{{ trigger.event.data.new_state.attributes.event_id }}{% endraw %} action: notify.mobile_app_your_device # Replace with your notification target +mode: single +max_exceeded: silent
409-412: Fix warning message formattingThe warning message should be simplified and properly formatted:
-**Warning:** - -Similar to NFC, an event is triggered both when a fingerprint is recognized and when it is not recognized. However, unlike NFC, at the time of implementation, no fingerprint ID is included in the event if the fingerprint is unknown. +{% warning %} +Similar to NFC, an event is triggered both when a fingerprint is recognized and when it is not recognized. However, unlike NFC, at the time of implementation, no fingerprint ID is included in the event if the fingerprint is unknown. +{% endwarning %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/unifiprotect.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/unifiprotect.markdown
[uncategorized] ~303-~303: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...n. This ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
source/_integrations/unifiprotect.markdown (4)
279-301: Add error handling for missing event attributesWhile the automation is well-structured, it should handle cases where event attributes might be missing.
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 %} + }}/{{ trigger.from_state.attributes.event_id | default('') }}{% endraw %} video: >- {% raw %}/api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ - trigger.from_state.attributes.event_id }}{% endraw %} + trigger.from_state.attributes.event_id | default('') }}{% endraw %}
319-336: Enhance the doorbell ring automation robustnessThe automation could be improved with better error handling and a more robust condition check.
conditions: - condition: template value_template: | - {% raw %}{{ 'ring' in trigger.event.data.new_state.attributes.event_types }}{% endraw %} + {% raw %}{{ + trigger.event.data.new_state is not none and + trigger.event.data.new_state.attributes.event_types is defined and + 'ring' in trigger.event.data.new_state.attributes.event_types + }}{% endraw %} actions: - data: message: Someone is at the door! title: Doorbell Notification + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) + }}/{{ trigger.event.data.new_state.attributes.event_id | default('') }}{% endraw %} action: notify.mobile_app_your_device
351-376: Add logging for security monitoringThe automation handles NFC validation well, but could benefit from logging unsuccessful attempts for security monitoring.
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: + - service: system_log.write + data: + message: > + {% raw %}NFC card scan: {{ trigger.event.data.new_state.attributes.nfc_id }} + {{ ' (unauthorized)' if trigger.event.data.new_state.attributes.nfc_id not in ['ABCDEF1234', 'OTHER_ALLOWED_ID'] else '' }}{% endraw %} + level: warning - data: message: >- {% raw %}The NFC card with ID {{ trigger.event.data.new_state.attributes.nfc_id
393-415: Enhance notification content with timestampThe automation handles fingerprint validation well, but the notification could be more informative.
- service: notify.mobile_app_your_device data: - {% raw %}message: "Fingerprint identified with ID: {{ trigger.event.data.new_state.attributes.ulp_id }}"{% endraw %} + {% raw %}message: > + Fingerprint identified at {{ trigger.event.time_fired.strftime('%I:%M %p') }} + ID: {{ trigger.event.data.new_state.attributes.ulp_id }}{% endraw %} title: "Fingerprint Scan Notification" + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) + }}/{{ trigger.event.data.new_state.attributes.event_id | default('') }}{% endraw %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/unifiprotect.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/unifiprotect.markdown
[uncategorized] ~303-~303: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...n. This ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
🔇 Additional comments (1)
source/_integrations/unifiprotect.markdown (1)
303-303: LGTM!
The current sentence structure is clear and readable.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~303-~303: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...n. This ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
|
@coderabbitai review |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
source/_integrations/unifiprotect.markdown (3)
279-299: Enhance the notification automation example with additional validationThe automation example is well-structured but could be more robust with additional validation.
Consider adding these improvements:
trigger: - entity_id: - binary_sensor.g5_bullet_motion # Replace with your camera entity trigger: state from: "on" to: "off" +condition: + - condition: template + value_template: > + {% raw %}{{ + trigger.from_state.attributes.event_id is defined and + trigger.from_state.attributes.event_id != none + }}{% endraw %} actions: - data: message: "Motion detected at Camera XXX" data: + # Only include media if event_id exists 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 %}
317-334: Enhance the doorbell ring automation with richer notificationsThe automation handles the basic case well but could provide more useful information in the notification.
Consider these improvements:
actions: - data: - message: Someone is at the door! + message: > + {% raw %}Someone rang the doorbell at {{ trigger.event.time_fired.strftime('%I:%M %p') }}{% endraw %} title: Doorbell Notification + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.event.data.new_state.attributes.event_id }}{% endraw %} action: notify.mobile_app_your_device # Replace with your notification target
391-413: Enhance fingerprint automation with richer notificationsThe automation handles fingerprint identification well but could provide more context in the notification.
Consider these improvements:
action: - service: notify.mobile_app_your_device data: - {% raw %}message: "Fingerprint identified with ID: {{ trigger.event.data.new_state.attributes.ulp_id }}"{% endraw %} + {% raw %}message: > + Fingerprint identified at {{ trigger.event.time_fired.strftime('%I:%M %p') }} + ID: {{ trigger.event.data.new_state.attributes.ulp_id }}{% endraw %} title: "Fingerprint Scan Notification" + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.event.data.new_state.attributes.event_id }}{% endraw %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/unifiprotect.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/unifiprotect.markdown
[uncategorized] ~301-~301: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...n. This ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
🔇 Additional comments (1)
source/_integrations/unifiprotect.markdown (1)
349-374: LGTM! Well-structured NFC automation with proper security considerations
The automation implements good security practices by validating the NFC ID against a whitelist and includes proper null checks.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
source/_integrations/unifiprotect.markdown (3)
279-299: Enhance the notification automation example with better error handling and messagingThe automation example could be improved with additional error handling and a more informative notification message.
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" + message: >- + {% raw %}Motion detected at {{ trigger.entity_id.split('.')[1]|replace('_', ' ')|title }} + Duration: {{ (as_timestamp(trigger.to_state.last_changed) - as_timestamp(trigger.from_state.last_changed))|round(1) }} seconds{% endraw %} data: image: >- - {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}{% endraw %} + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id|default('') }}{% endraw %} video: >- - {% raw %}/api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}{% endraw %} + {% raw %}/api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id|default('') }}{% endraw %} action: notify.mobile_app_your_device # Replace with your notification target mode: single max_exceeded: silent
317-334: Enhance the doorbell automation with media content and better error handlingThe doorbell automation could be improved by including the event thumbnail in the notification and adding null checks.
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 %} + {% raw %}{{ + trigger.event.data.new_state is not none and + 'ring' in (trigger.event.data.new_state.attributes.event_types|default([])) + }}{% endraw %} actions: - data: message: Someone is at the door! title: Doorbell Notification + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.event.data.new_state.attributes.event_id|default('') }}{% endraw %} action: notify.mobile_app_your_device # Replace with your notification target
390-412: Enhance the fingerprint notification with timestamp informationThe fingerprint automation could be improved by including the timestamp in the notification message.
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 %} + {% raw %}message: >- + Fingerprint identified with ID: {{ trigger.event.data.new_state.attributes.ulp_id }} + Time: {{ trigger.event.time_fired.strftime('%I:%M %p') }}{% endraw %} title: "Fingerprint Scan Notification"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/unifiprotect.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/unifiprotect.markdown
[uncategorized] ~301-~301: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...n. This ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
🔇 Additional comments (1)
source/_integrations/unifiprotect.markdown (1)
349-373: LGTM! Well-structured NFC automation example
The NFC automation example is well-implemented with proper null checks, ID validation, and security considerations.
Co-authored-by: J. Nick Koston <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (2)
source/_integrations/unifiprotect.markdown (2)
279-299: Add error handling for missing event attributesThe automation could be more robust by adding checks for missing event attributes.
trigger: - entity_id: - binary_sensor.g5_bullet_motion # Replace with your camera entity trigger: state from: "on" to: "off" +condition: + - condition: template + value_template: > + {% raw %}{{ + trigger.from_state.attributes.event_id is defined and + trigger.from_state.attributes.event_id != none + }}{% endraw %} 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
390-412: Enhance fingerprint notification with event media and timestampWhile the security implementation is solid, the notification could be more informative.
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 %} + {% raw %}message: > + Fingerprint identified at {{ trigger.event.time_fired.strftime('%I:%M %p') }} + Access granted for user with ID {{ trigger.event.data.new_state.attributes.ulp_id }}.{% endraw %} title: "Fingerprint Scan Notification" + data: + image: >- + {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.event.data.new_state.attributes.event_id }}{% endraw %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/unifiprotect.markdown(4 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/unifiprotect.markdown
[uncategorized] ~301-~301: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short).
Context: ...Waiting ensures that the event has ended and the video is accessible; otherwise, you...
(COMMA_COMPOUND_SENTENCE_2)
🔇 Additional comments (1)
source/_integrations/unifiprotect.markdown (1)
349-373: LGTM! Secure implementation with proper validation
The automation correctly implements security best practices by validating NFC IDs against a whitelist and including proper null checks.
bdraco
removed
in-progress
frenck
added
the
cherry-picked
Co-authored-by: J. Nick Koston <[email protected]>
Proposed change
add examples for UniFi Protect integration
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
New Features
Documentation