From a5f241d5bdbefbbae08a4166c89640751624440b Mon Sep 17 00:00:00 2001 From: Blake Blackshear Date: Mon, 13 Sep 2021 22:02:12 -0500 Subject: [PATCH] cleanup ha notification docs --- docs/docs/guides/ha_notifications.md | 56 +++++++++++ docs/docs/integrations/home-assistant.md | 122 +++-------------------- docs/docs/integrations/howtos.md | 11 -- docs/sidebars.js | 1 + 4 files changed, 69 insertions(+), 121 deletions(-) create mode 100644 docs/docs/guides/ha_notifications.md delete mode 100644 docs/docs/integrations/howtos.md diff --git a/docs/docs/guides/ha_notifications.md b/docs/docs/guides/ha_notifications.md new file mode 100644 index 000000000..9013cad40 --- /dev/null +++ b/docs/docs/guides/ha_notifications.md @@ -0,0 +1,56 @@ +--- +id: ha_notifications +title: Home Assistant Notifications +--- + +The best way to get started with notifications for Frigate is to use the [Blueprint](https://community.home-assistant.io/t/frigate-mobile-app-notifications/311091). You can use the yaml generated from the Blueprint as a starting point and customize from there. + +It is generally recommended to trigger notifications based on the `frigate/events` mqtt topic. This provides the event_id needed to fetch [thumbnails/snapshots/clips](/integrations/home-assistant#notification-api) and other useful information to customize when and where you want to receive alerts. The data is published in the form of a change feed, which means you can reference the "previous state" of the object in the `before` section and the "current state" of the object in the `after` section. You can see an example [here](/integrations/mqtt#frigateevents). + +Here is a simple example of a notification automation of events which will update the existing notification for each change. This means the image you see in the notification will update as frigate finds a "better" image. + +```yaml +automation: + - alias: Notify of events + trigger: + platform: mqtt + topic: frigate/events + action: + - service: notify.mobile_app_pixel_3 + data_template: + message: 'A {{trigger.payload_json["after"]["label"]}} was detected.' + data: + image: 'https://your.public.hass.address.com/api/frigate/notifications/{{trigger.payload_json["after"]["id"]}}/thumbnail.jpg?format=android' + tag: '{{trigger.payload_json["after"]["id"]}}' + when: '{{trigger.payload_json["after"]["start_time"]|int}}' +``` + +## Conditions + +Conditions with the `before` and `after` values allow a high degree of customization for automations. + +When a person enters a zone named yard + +```yaml +condition: + - "{{ trigger.payload_json['after']['label'] == 'person' }}" + - "{{ 'yard' in trigger.payload_json['after']['entered_zones'] }}" +``` + +When a person leaves a zone named yard + +```yaml +condition: + - "{{ trigger.payload_json['after']['label'] == 'person' }}" + - "{{ 'yard' in trigger.payload_json['before']['current_zones'] }}" + - "{{ not 'yard' in trigger.payload_json['after']['current_zones'] }}" +``` + +Notify for dogs in the front with a high top score + +```yaml +condition: + - "{{ trigger.payload_json['after']['label'] == 'dog' }}" + - "{{ trigger.payload_json['after']['camera'] == 'front' }}" + - "{{ trigger.payload_json['after']['top_score'] > 0.98 }}" +``` diff --git a/docs/docs/integrations/home-assistant.md b/docs/docs/integrations/home-assistant.md index 6de583423..165eef1c4 100644 --- a/docs/docs/integrations/home-assistant.md +++ b/docs/docs/integrations/home-assistant.md @@ -1,7 +1,6 @@ --- id: home-assistant -title: Integration with Home Assistant -sidebar_label: Home Assistant +title: Home Assistant Integration --- The best way to integrate with Home Assistant is to use the [official integration](https://github.com/blakeblackshear/frigate-hass-integration). @@ -77,131 +76,34 @@ Home Assistant > Configuration > Integrations > Frigate > Options The integration provides: -- Rich UI with thumbnails for browsing event recordings -- Rich UI for browsing 24/7 recordings by month, day, camera, time +- Browsing event recordings with thumbnails +- Browsing snapshots +- Browsing recordings by month, day, camera, time This is accessible via "Media Browser" on the left menu panel in Home Assistant. -## API +## Notification API -- Notification API with public facing endpoints for images in notifications +Many people do not want to expose Frigate to the web, so the integration creates some public API endpoints that can be used for notifications. -### Notifications - -Frigate publishes event information in the form of a change feed via MQTT. This -allows lots of customization for notifications to meet your needs. Event changes -are published with `before` and `after` information as shown -[here](#frigateevents). Note that some people may not want to expose frigate to -the web, so you can leverage the HA API that frigate custom_integration ties -into (which is exposed to the web, and thus can be used for mobile notifications -etc): - -To load an image taken by frigate from Home Assistants API see below: +To load a thumbnail for an event: ``` https://HA_URL/api/frigate/notifications//thumbnail.jpg ``` -To load a video clip taken by frigate from Home Assistants API : +To load a snapshot for an event: ``` -https://HA_URL/api/frigate/notifications///clip.mp4 +https://HA_URL/api/frigate/notifications//snapshot.jpg ``` -Here is a simple example of a notification automation of events which will update the existing notification for each change. This means the image you see in the notification will update as frigate finds a "better" image. +To load a video clip of an event: -```yaml -automation: - - alias: Notify of events - trigger: - platform: mqtt - topic: frigate/events - action: - - service: notify.mobile_app_pixel_3 - data_template: - message: 'A {{trigger.payload_json["after"]["label"]}} was detected.' - data: - image: 'https://your.public.hass.address.com/api/frigate/notifications/{{trigger.payload_json["after"]["id"]}}/thumbnail.jpg?format=android' - tag: '{{trigger.payload_json["after"]["id"]}}' - when: '{{trigger.payload_json["after"]["start_time"]|int}}' ``` - -```yaml -automation: - - alias: When a person enters a zone named yard - trigger: - platform: mqtt - topic: frigate/events - condition: - - "{{ trigger.payload_json['after']['label'] == 'person' }}" - - "{{ 'yard' in trigger.payload_json['after']['entered_zones'] }}" - action: - - service: notify.mobile_app_pixel_3 - data_template: - message: "A {{trigger.payload_json['after']['label']}} has entered the yard." - data: - image: "https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg" - tag: "{{trigger.payload_json['after']['id']}}" - when: '{{trigger.payload_json["after"]["start_time"]|int}}' -``` - -```yaml -- alias: When a person leaves a zone named yard - trigger: - platform: mqtt - topic: frigate/events - condition: - - "{{ trigger.payload_json['after']['label'] == 'person' }}" - - "{{ 'yard' in trigger.payload_json['before']['current_zones'] }}" - - "{{ not 'yard' in trigger.payload_json['after']['current_zones'] }}" - action: - - service: notify.mobile_app_pixel_3 - data_template: - message: "A {{trigger.payload_json['after']['label']}} has left the yard." - data: - image: "https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg" - tag: "{{trigger.payload_json['after']['id']}}" - when: '{{trigger.payload_json["after"]["start_time"]|int}}' -``` - -```yaml -- alias: Notify for dogs in the front with a high top score - trigger: - platform: mqtt - topic: frigate/events - condition: - - "{{ trigger.payload_json['after']['label'] == 'dog' }}" - - "{{ trigger.payload_json['after']['camera'] == 'front' }}" - - "{{ trigger.payload_json['after']['top_score'] > 0.98 }}" - action: - - service: notify.mobile_app_pixel_3 - data_template: - message: "High confidence dog detection." - data: - image: "https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg" - tag: "{{trigger.payload_json['after']['id']}}" - when: '{{trigger.payload_json["after"]["start_time"]|int}}' -``` - -If you are using telegram, you can fetch the image directly from Frigate: - -```yaml -automation: - - alias: Notify of events - trigger: - platform: mqtt - topic: frigate/events - action: - - service: notify.telegram_full - data_template: - message: 'A {{trigger.payload_json["after"]["label"]}} was detected.' - data: - photo: - # this url should work for addon users - - url: 'http://ccab4aaf-frigate:5000/api/events/{{trigger.payload_json["after"]["id"]}}/thumbnail.jpg' - caption: 'A {{trigger.payload_json["after"]["label"]}} was detected on {{ trigger.payload_json["after"]["camera"] }} camera' +https://HA_URL/api/frigate/notifications//clip.mp4 ``` @@ -282,6 +184,6 @@ which server they are referring to. ## FAQ -### If I am detecting multiple objects, how do I assign the correct `binary_sensor` to the camera in HomeKit? +#### If I am detecting multiple objects, how do I assign the correct `binary_sensor` to the camera in HomeKit? The [HomeKit integration](https://www.home-assistant.io/integrations/homekit/) randomly links one of the binary sensors (motion sensor entities) grouped with the camera device in Home Assistant. You can specify a `linked_motion_sensor` in the Home Assistant [HomeKit configuration](https://www.home-assistant.io/integrations/homekit/#linked_motion_sensor) for each camera. diff --git a/docs/docs/integrations/howtos.md b/docs/docs/integrations/howtos.md deleted file mode 100644 index 9392caf0a..000000000 --- a/docs/docs/integrations/howtos.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -id: howtos -title: Community Guides -sidebar_label: Community Guides ---- - -## Communitiy Guides/How-To's - -- Best Camera AI Person & Object Detection - How to Setup Frigate w/ Home Assistant - digiblurDIY [YouTube](https://youtu.be/V8vGdoYO6-Y) - [Article](https://www.digiblur.com/2021/05/how-to-setup-frigate-home-assistant.html) -- Even More Free Local Object Detection with Home Assistant - Frigate Install - Everything Smart Home [YouTube](https://youtu.be/pqDCEZSVeRk) -- Home Assistant Frigate integration for local image recognition - KPeyanski [YouTube](https://youtu.be/Q2UT78lFQpo) - [Article](https://peyanski.com/home-assistant-frigate-integration/) diff --git a/docs/sidebars.js b/docs/sidebars.js index 104ee2937..267f4ed0b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -9,6 +9,7 @@ module.exports = { 'guides/camera_setup', 'guides/getting_started', 'guides/false_positives', + 'guides/ha_notifications', ], Configuration: [ 'configuration/index',