From 5d0984998df93dc449985220a110352c12591061 Mon Sep 17 00:00:00 2001 From: zacho112 Date: Thu, 3 Jun 2021 18:50:55 +0200 Subject: [PATCH 1/6] Update detectors.md Include how to use the native Coral on the Coral Dev Board --- docs/docs/configuration/detectors.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/docs/configuration/detectors.md b/docs/docs/configuration/detectors.md index a7bbdab79..3ff3c9709 100644 --- a/docs/docs/configuration/detectors.md +++ b/docs/docs/configuration/detectors.md @@ -42,6 +42,15 @@ detectors: device: pci:1 ``` +Native Corals (Dev Board): + +```yaml +detectors: + coral: + type: edgetpu + device: '' +``` + Mixing Corals: ```yaml From 03e756dd27082ea665be03638a21e5d51ab7f895 Mon Sep 17 00:00:00 2001 From: zacho112 Date: Mon, 14 Jun 2021 19:31:09 +0200 Subject: [PATCH 2/6] Update detectors.md --- docs/docs/configuration/detectors.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/docs/configuration/detectors.md b/docs/docs/configuration/detectors.md index 3ff3c9709..58ec474ef 100644 --- a/docs/docs/configuration/detectors.md +++ b/docs/docs/configuration/detectors.md @@ -30,6 +30,15 @@ detectors: device: usb:1 ``` +Native Coral (Dev Board): + +```yaml +detectors: + coral: + type: edgetpu + device: '' +``` + Multiple PCIE/M.2 Corals: ```yaml @@ -42,15 +51,6 @@ detectors: device: pci:1 ``` -Native Corals (Dev Board): - -```yaml -detectors: - coral: - type: edgetpu - device: '' -``` - Mixing Corals: ```yaml From 3bc75ae931adfb614a0555b50001aa182aad3921 Mon Sep 17 00:00:00 2001 From: Dermot Duffy Date: Sat, 26 Jun 2021 13:52:46 -0700 Subject: [PATCH 3/6] Refresh the HA integration documentation. --- docs/docs/usage/home-assistant.md | 155 +++++++++++++++++++++++++++--- 1 file changed, 144 insertions(+), 11 deletions(-) diff --git a/docs/docs/usage/home-assistant.md b/docs/docs/usage/home-assistant.md index 45764e01a..a930bf0d0 100644 --- a/docs/docs/usage/home-assistant.md +++ b/docs/docs/usage/home-assistant.md @@ -4,31 +4,89 @@ title: Integration with Home Assistant sidebar_label: Home Assistant --- -The best way to integrate with Home Assistant is to use the [official integration](https://github.com/blakeblackshear/frigate-hass-integration). When configuring the integration, you will be asked for the `Host` of your frigate instance. This value should be the url you use to access Frigate in the browser and will look like `http://:5000/`. If you are using HassOS with the addon, the host should be `http://ccab4aaf-frigate:5000` (or `http://ccab4aaf-frigate-beta:5000` if your are using the beta version of the addon). Home Assistant needs access to port 5000 (api) and 1935 (rtmp) for all features. The integration will setup the following entities within Home Assistant: +The best way to integrate with Home Assistant is to use the [official integration](https://github.com/blakeblackshear/frigate-hass-integration). -## Sensors: +## Installation -- Stats to monitor frigate performance -- Object counts for all zones and cameras +Available via HACS as a [custom repository](https://hacs.xyz/docs/faq/custom_repositories). To install: -## Cameras: + * Add the custom repository: -- Cameras for image of the last detected object for each camera -- Camera entities with stream support (requires RTMP) +``` +Home Assistant > HACS > Integrations > [...] > Custom Repositories +``` -## Media Browser: +| Key | Value | +| -------------- | ----------------------------------------------------------- | +| Repository URL | https://github.com/blakeblackshear/frigate-hass-integration | +| Category | Integration | + + * Use [HACS](https://hacs.xyz/) to install the integration: +``` +Home Assistant > HACS > Integrations > "Explore & Add Integrations" > Frigate +``` + * Restart Home Assistant. + * Then add/configure the integration: +``` +Home Assistant > Configuration > Integrations > Add Integration > Frigate +``` + +Note: You will also need +[media_source](https://www.home-assistant.io/integrations/media_source/) enabled +in your Home Assistant configuration for the Media Browser to appear. + +## Configuration + +When configuring the integration, you will be asked for the following parameters: + + +| Variable | Description | +| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| URL | The `URL` of your frigate instance, the URL you use to access Frigate in the browser. This may look like `http://:5000/`. If you are using HassOS with the addon, the URL should be `http://ccab4aaf-frigate:5000` (or `http://ccab4aaf-frigate-beta:5000` if your are using the beta version of the addon). Live streams required port 1935, see [RTMP streams](#streams) | + + +## Options + +``` +Home Assistant > Configuration > Integrations > Frigate > Options +``` + +| Option | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| RTMP URL Template | A [jinja2](https://jinja.palletsprojects.com/) template that is used to override the standard RTMP stream URL (e.g. for use with reverse proxies). This option is only shown to users who have [advanced mode](https://www.home-assistant.io/blog/2019/07/17/release-96/#advanced-mode) enabled. See [RTMP streams](#streams) below. | + +## Entities Provided + +| Platform | Description | +| --------------- | --------------------------------------------------------------------------------- | +| `camera` | Live camera stream (requires RTMP), camera for image of the last detected object. | +| `sensor` | States to monitor Frigate performance, object counts for all zones and cameras. | +| `switch` | Switch entities to toggle detection, clips and snapshots. | +| `binary_sensor` | A "motion" binary sensor entity per camera/zone/object. | + +## Media Browser Support + +The integration provides: - Rich UI with thumbnails for browsing event clips - Rich UI for browsing 24/7 recordings by month, day, camera, time -## API: +This is accessible via "Media Browser" on the left menu panel in Home Assistant. + + +## API - Notification API with public facing endpoints for images in 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): +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: @@ -131,3 +189,78 @@ automation: - 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' ``` + + +## RTMP stream + +In order for the live streams to function they need to be accessible on the RTMP +port (default: `1935`) at `:1935`. Home Assistant will directly +connect to that streaming port when the live camera is viewed. + +#### RTMP URL Template + +For advanced usecases, this behavior can be changed with the [RTMP URL +template](#options) option. When set, this string will override the default stream +address that is derived from the default behavior described above. This option supports +[jinja2 templates](https://jinja.palletsprojects.com/) and has the `camera` dict +variables from [Frigate API](https://blakeblackshear.github.io/frigate/usage/api#apiconfig) +available for the template. Note that no Home Assistant state is available to the +template, only the camera dict from Frigate. + +This is potentially useful when Frigate is behind a reverse proxy, and/or when +the default stream port is otherwise not accessible to Home Assistant (e.g. +firewall rules). + +###### RTMP URL Template Examples + +Use a different port number: + +``` +rtmp://:2000/live/front_door +``` + +Use the camera name in the stream URL: + +``` +rtmp://:2000/live/{{ name }} +``` + +Use the camera name in the stream URL, converting it to lowercase first: + +``` +rtmp://:2000/live/{{ name|lower }} +``` + +## Multiple Instance Support + +The Frigate integration seamlessly supports the use of multiple Frigate servers. + +### Requirements for Multiple Instances + +In order for multiple Frigate instances to function correctly, the +`topic_prefix` and `client_id` parameters must be set differently per server. +See [MQTT +configuration](https://blakeblackshear.github.io/frigate/configuration/index#mqtt) +for how to set these. + +#### API URLs + +When multiple Frigate instances are configured, [API](#api) URLs should include an +identifier to tell Home Assistant which Frigate instance to refer to. The +identifier used is the MQTT `client_id` paremeter included in the configuration, +and is used like so: + +``` +https://HA_URL/api/frigate//notifications//thumbnail.jpg +``` + +``` +https://HA_URL/api/frigate//clips/front_door-1624599978.427826-976jaa.mp4 +``` + +#### Default Treatment + +When a single Frigate instance is configured, the `client-id` parameter need not +be specified in URLs/identifiers -- that single instance is assumed. When +multiple Frigate instances are configured, the user **must** explicitly specify +which server they are referring to. \ No newline at end of file From adf2bc078c255dbc575d79477d5ff752954f19f5 Mon Sep 17 00:00:00 2001 From: Craig Dennis Date: Mon, 26 Jul 2021 13:49:08 +0100 Subject: [PATCH 4/6] Include details about stream passthrough Refs #1440 Indicate that width and height are only used for the detect role and so other streams for with other roles are passed through and resolution is not needed. --- docs/docs/configuration/cameras.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/configuration/cameras.md b/docs/docs/configuration/cameras.md index faf871f07..5184e516c 100644 --- a/docs/docs/configuration/cameras.md +++ b/docs/docs/configuration/cameras.md @@ -38,6 +38,8 @@ cameras: fps: 5 ``` +`width`, `height`, and `fps` are only used for the `detect` role. Other streams are passed through, so there is no need to specify the resolution. + ## Masks & Zones ### Masks From abef002af8af14a6190408d72d52d2a755046826 Mon Sep 17 00:00:00 2001 From: shred86 <32663154+shred86@users.noreply.github.com> Date: Sat, 14 Aug 2021 05:27:43 -0700 Subject: [PATCH 5/6] Add FAQ section (#1459) * Add FAQ section Add FAQ section and verbiage about a finding with camera motion sensors in HomeKit. * Changes made based on inputs * Fix markdown Co-authored-by: Blake Blackshear --- docs/docs/usage/home-assistant.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/docs/usage/home-assistant.md b/docs/docs/usage/home-assistant.md index a930bf0d0..064ff5aad 100644 --- a/docs/docs/usage/home-assistant.md +++ b/docs/docs/usage/home-assistant.md @@ -263,4 +263,11 @@ https://HA_URL/api/frigate//clips/front_door-1624599978.427826-976jaa When a single Frigate instance is configured, the `client-id` parameter need not be specified in URLs/identifiers -- that single instance is assumed. When multiple Frigate instances are configured, the user **must** explicitly specify -which server they are referring to. \ No newline at end of file +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? + +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. + From 58c0d97b5f6b8b8baaeb7403ed8dcbc6eea7293c Mon Sep 17 00:00:00 2001 From: Charles Munger Date: Fri, 6 Aug 2021 00:13:20 -0700 Subject: [PATCH 6/6] Include timestamps for notification examples In the homeassistant app, the notification timestamp is generated when the push message is received by the app. Delays caused by servers, device load, or network latency/availability will delay those pushes - so in the following case: 1:00 - A dog is detected in the front 1:02 - It stops moving around or leaves view, last notification push sent 1:05 - The phone connects to the network The user, seeing the alert at 1:05, will see that the notification occurred "a few seconds ago", since the timestamp the app sends to the OS was at 1:05. By adding the `when` parameter, it will instead correctly show that the event was triggered at 1:00. This is exacerbated by the fact that the default behavior of android pushes won't wake the device from deep sleep - in order to receive it as a high priority notification, the additional parameters ``` data: priority: high ttl: 0 ``` have to be added. --- docs/docs/usage/home-assistant.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/docs/usage/home-assistant.md b/docs/docs/usage/home-assistant.md index 064ff5aad..bf0b577b1 100644 --- a/docs/docs/usage/home-assistant.md +++ b/docs/docs/usage/home-assistant.md @@ -10,7 +10,7 @@ The best way to integrate with Home Assistant is to use the [official integratio Available via HACS as a [custom repository](https://hacs.xyz/docs/faq/custom_repositories). To install: - * Add the custom repository: +- Add the custom repository: ``` Home Assistant > HACS > Integrations > [...] > Custom Repositories @@ -21,12 +21,15 @@ Home Assistant > HACS > Integrations > [...] > Custom Repositories | Repository URL | https://github.com/blakeblackshear/frigate-hass-integration | | Category | Integration | - * Use [HACS](https://hacs.xyz/) to install the integration: +- Use [HACS](https://hacs.xyz/) to install the integration: + ``` Home Assistant > HACS > Integrations > "Explore & Add Integrations" > Frigate ``` - * Restart Home Assistant. - * Then add/configure the integration: + +- Restart Home Assistant. +- Then add/configure the integration: + ``` Home Assistant > Configuration > Integrations > Add Integration > Frigate ``` @@ -39,12 +42,12 @@ in your Home Assistant configuration for the Media Browser to appear. When configuring the integration, you will be asked for the following parameters: - | Variable | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | URL | The `URL` of your frigate instance, the URL you use to access Frigate in the browser. This may look like `http://:5000/`. If you are using HassOS with the addon, the URL should be `http://ccab4aaf-frigate:5000` (or `http://ccab4aaf-frigate-beta:5000` if your are using the beta version of the addon). Live streams required port 1935, see [RTMP streams](#streams) | + ## Options ``` @@ -74,6 +77,7 @@ The integration provides: This is accessible via "Media Browser" on the left menu panel in Home Assistant. + ## API - Notification API with public facing endpoints for images in notifications @@ -115,6 +119,7 @@ automation: 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 @@ -133,6 +138,7 @@ automation: 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 @@ -151,6 +157,7 @@ automation: 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 @@ -169,6 +176,7 @@ automation: 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: @@ -191,6 +199,7 @@ automation: ``` + ## RTMP stream In order for the live streams to function they need to be accessible on the RTMP @@ -233,7 +242,7 @@ rtmp://:2000/live/{{ name|lower }} ## Multiple Instance Support -The Frigate integration seamlessly supports the use of multiple Frigate servers. +The Frigate integration seamlessly supports the use of multiple Frigate servers. ### Requirements for Multiple Instances @@ -270,4 +279,3 @@ which server they are referring to. ### 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. -