blakeblackshear.frigate/064d4f6f.b39936e3.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[3],{64:function(e,t,a){"use strict";a.r(t),a.d(t,"frontMatter",(function(){return o})),a.d(t,"metadata",(function(){return s})),a.d(t,"toc",(function(){return l})),a.d(t,"default",(function(){return b}));var n=a(3),i=a(7),r=(a(0),a(99)),o={id:"home-assistant",title:"Integration with Home Assistant",sidebar_label:"Home Assistant"},s={unversionedId:"usage/home-assistant",id:"usage/home-assistant",isDocsHomePage:!1,title:"Integration with Home Assistant",description:"The best way to integrate with Home Assistant is to use the official integration.",source:"@site/docs/usage/home-assistant.md",slug:"/usage/home-assistant",permalink:"/frigate/usage/home-assistant",editUrl:"https://github.com/blakeblackshear/frigate/edit/master/docs/docs/usage/home-assistant.md",version:"current",sidebar_label:"Home Assistant",sidebar:"docs",previous:{title:"Advanced",permalink:"/frigate/configuration/advanced"},next:{title:"Web Interface",permalink:"/frigate/usage/web"}},l=[{value:"Installation",id:"installation",children:[{value:"Preparation",id:"preparation",children:[]},{value:"Integration installation",id:"integration-installation",children:[]},{value:"(Optional) Lovelace Card Installation",id:"optional-lovelace-card-installation",children:[]}]},{value:"Configuration",id:"configuration",children:[]},{value:"Options",id:"options",children:[]},{value:"Entities Provided",id:"entities-provided",children:[]},{value:"Media Browser Support",id:"media-browser-support",children:[]},{value:"API",id:"api",children:[{value:"Notifications",id:"notifications",children:[]}]},{value:"RTMP stream",id:"rtmp-stream",children:[]},{value:"Multiple Instance Support",id:"multiple-instance-support",children:[{value:"Requirements for Multiple Instances",id:"requirements-for-multiple-instances",children:[]}]},{value:"FAQ",id:"faq",children:[{value:"If I am detecting multiple objects, how do I assign the correct <code>binary_sensor</code> to the camera in HomeKit?",id:"if-i-am-detecting-multiple-objects-how-do-i-assign-the-correct-binary_sensor-to-the-camera-in-homekit",children:[]}]}],c={toc:l};function b(e){var t=e.components,a=Object(i.a)(e,["components"]);return Object(r.b)("wrapper",Object(n.a)({},c,a,{components:t,mdxType:"MDXLayout"}),Object(r.b)("p",null,"The best way to integrate with Home Assistant is to use the ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://github.com/blakeblackshear/frigate-hass-integration"}),"official integration"),"."),Object(r.b)("h2",{id:"installation"},"Installation"),Object(r.b)("h3",{id:"preparation"},"Preparation"),Object(r.b)("p",null,"The Frigate integration requires the ",Object(r.b)("inlineCode",{parentName:"p"},"mqtt")," integration to be installed and\nmanually configured first."),Object(r.b)("p",null,"See the ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://www.home-assistant.io/integrations/mqtt/"}),"MQTT integration\ndocumentation")," for more\ndetails."),Object(r.b)("h3",{id:"integration-installation"},"Integration installation"),Object(r.b)("p",null,"Available via HACS as a default repository. To install:"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"Use ",Object(r.b)("a",Object(n.a)({parentName:"li"},{href:"https://hacs.xyz/"}),"HACS")," to install the integration:")),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),'Home Assistant > HACS > Integrations > "Explore & Add Integrations" > Frigate\n')),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"Restart Home Assistant."),Object(r.b)("li",{parentName:"ul"},"Then add/configure the integration:")),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"Home Assistant > Configuration > Integrations > Add Integration > Frigate\n")),Object(r.b)("p",null,"Note: You will also need\n",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://www.home-assistant.io/integrations/media_source/"}),"media_source")," enabled\nin your Home Assistant configuration for the Media Browser to appear."),Object(r.b)("h3",{id:"optional-lovelace-card-installation"},"(Optional) Lovelace Card Installation"),Object(r.b)("p",null,"To install the optional companion Lovelace card, please see the ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://github.com/dermotduffy/frigate-hass-card"}),"separate\ninstallation instructions")," for\nthat card."),Object(r.b)("h2",{id:"configuration"},"Configuration"),Object(r.b)("p",null,"When configuring the integration, you will be asked for the following parameters:"),Object(r.b)("table",null,Object(r.b)("thead",{parentName:"table"},Object(r.b)("tr",{parentName:"thead"},Object(r.b)("th",Object(n.a)({parentName:"tr"},{align:null}),"Variable"),Object(r.b)("th",Object(n.a)({parentName:"tr"},{align:null}),"Description"))),Object(r.b)("tbody",{parentName:"table"},Object(r.b)("tr",{parentName:"tbody"},Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"URL"),Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"The ",Object(r.b)("inlineCode",{parentName:"td"},"URL")," of your frigate instance, the URL you use to access Frigate in the browser. This may look like ",Object(r.b)("inlineCode",{parentName:"td"},"http://<host>:5000/"),". If you are using HassOS with the addon, the URL should be ",Object(r.b)("inlineCode",{parentName:"td"},"http://ccab4aaf-frigate:5000")," (or ",Object(r.b)("inlineCode",{parentName:"td"},"http://ccab4aaf-frigate-beta:5000")," if your are using the beta version of the addon). Live streams required port 1935, see ",Object(r.b)("a",Object(n.a)({parentName:"td"},{href:"#streams"}),"RTMP streams"))))),Object(r.b)("a",{name:"options"}),Object(r.b)("h2",{id:"options"},"Options"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"Home Assistant > Configuration > Integrations > Frigate > Options\n")),Object(r.b)("table",null,Object(r.b)("thead",{parentName:"table"},Object(r.b)("tr",{parentName:"thead"},Object(r.b)("th",Object(n.a)({parentName:"tr"},{align:null}),"Option"),Object(r.b)("th",Object(n.a)({parentName:"tr"},{align:null}),"Description"))),Object(r.b)("tbody",{parentName:"table"},Object(r.b)("tr",{parentName:"tbody"},Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"RTMP URL Template"),Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"A ",Object(r.b)("a",Object(n.a)({parentName:"td"},{href:"https://jinja.palletsprojects.com/"}),"jinja2")," 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 ",Object(r.b)("a",Object(n.a)({parentName:"td"},{href:"https://www.home-assistant.io/blog/2019/07/17/release-96/#advanced-mode"}),"advanced mode")," enabled. See ",Object(r.b)("a",Object(n.a)({parentName:"td"},{href:"#streams"}),"RTMP streams")," below.")))),Object(r.b)("h2",{id:"entities-provided"},"Entities Provided"),Object(r.b)("table",null,Object(r.b)("thead",{parentName:"table"},Object(r.b)("tr",{parentName:"thead"},Object(r.b)("th",Object(n.a)({parentName:"tr"},{align:null}),"Platform"),Object(r.b)("th",Object(n.a)({parentName:"tr"},{align:null}),"Description"))),Object(r.b)("tbody",{parentName:"table"},Object(r.b)("tr",{parentName:"tbody"},Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),Object(r.b)("inlineCode",{parentName:"td"},"camera")),Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"Live camera stream (requires RTMP), camera for image of the last detected object.")),Object(r.b)("tr",{parentName:"tbody"},Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),Object(r.b)("inlineCode",{parentName:"td"},"sensor")),Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"States to monitor Frigate performance, object counts for all zones and cameras.")),Object(r.b)("tr",{parentName:"tbody"},Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),Object(r.b)("inlineCode",{parentName:"td"},"switch")),Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),"Switch entities to toggle detection, clips and snapshots.")),Object(r.b)("tr",{parentName:"tbody"},Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),Object(r.b)("inlineCode",{parentName:"td"},"binary_sensor")),Object(r.b)("td",Object(n.a)({parentName:"tr"},{align:null}),'A "motion" binary sensor entity per camera/zone/object.')))),Object(r.b)("h2",{id:"media-browser-support"},"Media Browser Support"),Object(r.b)("p",null,"The integration provides:"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"Rich UI with thumbnails for browsing event clips"),Object(r.b)("li",{parentName:"ul"},"Rich UI for browsing 24/7 recordings by month, day, camera, time")),Object(r.b)("p",null,'This is accessible via "Media Browser" on the left menu panel in Home Assistant.'),Object(r.b)("a",{name:"api"}),Object(r.b)("h2",{id:"api"},"API"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"Notification API with public facing endpoints for images in notifications")),Object(r.b)("h3",{id:"notifications"},"Notifications"),Object(r.b)("p",null,"Frigate publishes event information in the form of a change feed via MQTT. This\nallows lots of customization for notifications to meet your needs. Event changes\nare published with ",Object(r.b)("inlineCode",{parentName:"p"},"before")," and ",Object(r.b)("inlineCode",{parentName:"p"},"after")," information as shown\n",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"#frigateevents"}),"here"),". Note that some people may not want to expose frigate to\nthe web, so you can leverage the HA API that frigate custom_integration ties\ninto (which is exposed to the web, and thus can be used for mobile notifications\netc):"),Object(r.b)("p",null,"To load an image taken by frigate from Home Assistants API see below:"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"https://HA_URL/api/frigate/notifications/<event-id>/thumbnail.jpg\n")),Object(r.b)("p",null,"To load a video clip taken by frigate from Home Assistants API :"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"https://HA_URL/api/frigate/notifications/<event-id>/<camera>/clip.mp4\n")),Object(r.b)("p",null,'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.'),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{className:"language-yaml"}),'automation:\n  - alias: Notify of events\n    trigger:\n      platform: mqtt\n      topic: frigate/events\n    action:\n      - service: notify.mobile_app_pixel_3\n        data_template:\n          message: \'A {{trigger.payload_json["after"]["label"]}} was detected.\'\n          data:\n            image: \'https://your.public.hass.address.com/api/frigate/notifications/{{trigger.payload_json["after"]["id"]}}/thumbnail.jpg?format=android\'\n            tag: \'{{trigger.payload_json["after"]["id"]}}\'\n            when: \'{{trigger.payload_json["after"]["start_time"]|int}}\'\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{className:"language-yaml"}),"automation:\n  - alias: When a person enters a zone named yard\n    trigger:\n      platform: mqtt\n      topic: frigate/events\n    condition:\n      - \"{{ trigger.payload_json['after']['label'] == 'person' }}\"\n      - \"{{ 'yard' in trigger.payload_json['after']['entered_zones'] }}\"\n    action:\n      - service: notify.mobile_app_pixel_3\n        data_template:\n          message: \"A {{trigger.payload_json['after']['label']}} has entered the yard.\"\n          data:\n            image: \"https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg\"\n            tag: \"{{trigger.payload_json['after']['id']}}\"\n            when: '{{trigger.payload_json[\"after\"][\"start_time\"]|int}}'\n")),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{className:"language-yaml"}),"- alias: When a person leaves a zone named yard\n  trigger:\n    platform: mqtt\n    topic: frigate/events\n  condition:\n    - \"{{ trigger.payload_json['after']['label'] == 'person' }}\"\n    - \"{{ 'yard' in trigger.payload_json['before']['current_zones'] }}\"\n    - \"{{ not 'yard' in trigger.payload_json['after']['current_zones'] }}\"\n  action:\n    - service: notify.mobile_app_pixel_3\n      data_template:\n        message: \"A {{trigger.payload_json['after']['label']}} has left the yard.\"\n        data:\n          image: \"https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg\"\n          tag: \"{{trigger.payload_json['after']['id']}}\"\n          when: '{{trigger.payload_json[\"after\"][\"start_time\"]|int}}'\n")),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{className:"language-yaml"}),"- alias: Notify for dogs in the front with a high top score\n  trigger:\n    platform: mqtt\n    topic: frigate/events\n  condition:\n    - \"{{ trigger.payload_json['after']['label'] == 'dog' }}\"\n    - \"{{ trigger.payload_json['after']['camera'] == 'front' }}\"\n    - \"{{ trigger.payload_json['after']['top_score'] > 0.98 }}\"\n  action:\n    - service: notify.mobile_app_pixel_3\n      data_template:\n        message: \"High confidence dog detection.\"\n        data:\n          image: \"https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg\"\n          tag: \"{{trigger.payload_json['after']['id']}}\"\n          when: '{{trigger.payload_json[\"after\"][\"start_time\"]|int}}'\n")),Object(r.b)("p",null,"If you are using telegram, you can fetch the image directly from Frigate:"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{className:"language-yaml"}),'automation:\n  - alias: Notify of events\n    trigger:\n      platform: mqtt\n      topic: frigate/events\n    action:\n      - service: notify.telegram_full\n        data_template:\n          message: \'A {{trigger.payload_json["after"]["label"]}} was detected.\'\n          data:\n            photo:\n              # this url should work for addon users\n              - url: \'http://ccab4aaf-frigate:5000/api/events/{{trigger.payload_json["after"]["id"]}}/thumbnail.jpg\'\n                caption: \'A {{trigger.payload_json["after"]["label"]}} was detected on {{ trigger.payload_json["after"]["camera"] }} camera\'\n')),Object(r.b)("a",{name:"streams"}),Object(r.b)("h2",{id:"rtmp-stream"},"RTMP stream"),Object(r.b)("p",null,"In order for the live streams to function they need to be accessible on the RTMP\nport (default: ",Object(r.b)("inlineCode",{parentName:"p"},"1935"),") at ",Object(r.b)("inlineCode",{parentName:"p"},"<frigatehost>:1935"),". Home Assistant will directly\nconnect to that streaming port when the live camera is viewed."),Object(r.b)("h4",{id:"rtmp-url-template"},"RTMP URL Template"),Object(r.b)("p",null,"For advanced usecases, this behavior can be changed with the ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"#options"}),"RTMP URL\ntemplate")," option. When set, this string will override the default stream\naddress that is derived from the default behavior described above. This option supports\n",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://jinja.palletsprojects.com/"}),"jinja2 templates")," and has the ",Object(r.b)("inlineCode",{parentName:"p"},"camera")," dict\nvariables from ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://blakeblackshear.github.io/frigate/usage/api#apiconfig"}),"Frigate API"),"\navailable for the template. Note that no Home Assistant state is available to the\ntemplate, only the camera dict from Frigate."),Object(r.b)("p",null,"This is potentially useful when Frigate is behind a reverse proxy, and/or when\nthe default stream port is otherwise not accessible to Home Assistant (e.g.\nfirewall rules)."),Object(r.b)("h6",{id:"rtmp-url-template-examples"},"RTMP URL Template Examples"),Object(r.b)("p",null,"Use a different port number:"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"rtmp://<frigate_host>:2000/live/front_door\n")),Object(r.b)("p",null,"Use the camera name in the stream URL:"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"rtmp://<frigate_host>:2000/live/{{ name }}\n")),Object(r.b)("p",null,"Use the camera name in the stream URL, converting it to lowercase first:"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"rtmp://<frigate_host>:2000/live/{{ name|lower }}\n")),Object(r.b)("h2",{id:"multiple-instance-support"},"Multiple Instance Support"),Object(r.b)("p",null,"The Frigate integration seamlessly supports the use of multiple Frigate servers."),Object(r.b)("h3",{id:"requirements-for-multiple-instances"},"Requirements for Multiple Instances"),Object(r.b)("p",null,"In order for multiple Frigate instances to function correctly, the\n",Object(r.b)("inlineCode",{parentName:"p"},"topic_prefix")," and ",Object(r.b)("inlineCode",{parentName:"p"},"client_id")," parameters must be set differently per server.\nSee ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://blakeblackshear.github.io/frigate/configuration/index#mqtt"}),"MQTT\nconfiguration"),"\nfor how to set these."),Object(r.b)("h4",{id:"api-urls"},"API URLs"),Object(r.b)("p",null,"When multiple Frigate instances are configured, ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"#api"}),"API")," URLs should include an\nidentifier to tell Home Assistant which Frigate instance to refer to. The\nidentifier used is the MQTT ",Object(r.b)("inlineCode",{parentName:"p"},"client_id")," paremeter included in the configuration,\nand is used like so:"),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"https://HA_URL/api/frigate/<client-id>/notifications/<event-id>/thumbnail.jpg\n")),Object(r.b)("pre",null,Object(r.b)("code",Object(n.a)({parentName:"pre"},{}),"https://HA_URL/api/frigate/<client-id>/clips/front_door-1624599978.427826-976jaa.mp4\n")),Object(r.b)("h4",{id:"default-treatment"},"Default Treatment"),Object(r.b)("p",null,"When a single Frigate instance is configured, the ",Object(r.b)("inlineCode",{parentName:"p"},"client-id")," parameter need not\nbe specified in URLs/identifiers -- that single instance is assumed. When\nmultiple Frigate instances are configured, the user ",Object(r.b)("strong",{parentName:"p"},"must")," explicitly specify\nwhich server they are referring to."),Object(r.b)("h2",{id:"faq"},"FAQ"),Object(r.b)("h3",{id:"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 ",Object(r.b)("inlineCode",{parentName:"h3"},"binary_sensor")," to the camera in HomeKit?"),Object(r.b)("p",null,"The ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://www.home-assistant.io/integrations/homekit/"}),"HomeKit integration")," randomly links one of the binary sensors (motion sensor entities) grouped with the camera device in Home Assistant. You can specify a ",Object(r.b)("inlineCode",{parentName:"p"},"linked_motion_sensor")," in the Home Assistant ",Object(r.b)("a",Object(n.a)({parentName:"p"},{href:"https://www.home-assistant.io/integrations/homekit/#linked_motion_sensor"}),"HomeKit configuration")," for each camera."))}b.isMDXComponent=!0},99:function(e,t,a){"use strict";a.d(t,"a",(function(){return p})),a.d(t,"b",(function(){return u}));var n=a(0),i=a.n(n);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function s(e){for(var t=1;t<arguments.length;t++){var a=null!=arguments[t]?arguments[t]:{};t%2?o(Object(a),!0).forEach((function(t){r(e,t,a[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(a)):o(Object(a)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(a,t))}))}return e}function l(e,t){if(null==e)return{};var a,n,i=function(e,t){if(null==e)return{};var a,n,i={},r=Object.keys(e);for(n=0;n<r.length;n++)a=r[n],t.indexOf(a)>=0||(i[a]=e[a]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(n=0;n<r.length;n++)a=r[n],t.indexOf(a)>=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var c=i.a.createContext({}),b=function(e){var t=i.a.useContext(c),a=t;return e&&(a="function"==typeof e?e(t):s(s({},t),e)),a},p=function(e){var t=b(e.components);return i.a.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return i.a.createElement(i.a.Fragment,{},t)}},m=i.a.forwardRef((function(e,t){var a=e.components,n=e.mdxType,r=e.originalType,o=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),p=b(a),m=n,u=p["".concat(o,".").concat(m)]||p[m]||d[m]||r;return a?i.a.createElement(u,s(s({ref:t},c),{},{components:a})):i.a.createElement(u,s({ref:t},c))}));function u(e,t){var a=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var r=a.length,o=new Array(r);o[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:n,o[1]=s;for(var c=2;c<r;c++)o[c]=a[c];return i.a.createElement.apply(null,o)}return i.a.createElement.apply(null,a)}m.displayName="MDXCreateElement"}}]);