diff --git a/source/_integrations/nest.markdown b/source/_integrations/nest.markdown index e9a795f083a..10bfd6fb3b9 100644 --- a/source/_integrations/nest.markdown +++ b/source/_integrations/nest.markdown @@ -263,6 +263,8 @@ Home Assistant supports all SDM API features. However, every Camera or Doorbell - **RTSP**: These devices have an HLS stream served by the Home Assistant Core. These cameras support server-side `camera` actions like stream recording or image preview. See [Low Latency HLS](/integrations/stream#ll-hls) as a great option to enable to reduce stream latency. - **WebRTC**: These devices support direct browser to camera communication and a super low latency stream. A [Picture Glance Card](/dashboards/picture-glance/) can show the live stream in the grid with the *Camera View* set to `live` (not recommended for battery-powered cameras). `camera` actions like stream recording are *not supported*. +Given a camera named `Front Yard`, then the camera is created with a name such as `camera.front_yard`. + {% note %} This feature is enabled by the following permissions: @@ -272,10 +274,10 @@ This feature is enabled by the following permissions: {% endnote %} +All cameras also expose event entities for automation. Some camera models also +support capturing media (snapshots or clips) through device triggers. The table below summarizes the [supported SDM API features](https://developers.google.com/nest/device-access/supported-devices) for each device. -All cameras have motion and person triggers, however only some support capturing snapshots for events. The table below summarizes the [Supported SDM API features](https://developers.google.com/nest/device-access/supported-devices) for each device. - -| Device | Live Stream | Triggers / Events | Media Source
for Triggers / Events | +| Device | Live stream | Event entities / triggers | Media source
for triggers | | -------------------------------------------------------------------------------- | :---------------: | :--------------------------------: | :------------------------------------: | | Nest Cam (indoor, wired)
Nest Cam (outdoor, battery) | WebRTC | Motion
Person | N/A | | Nest Cam Indoor
Nest Cam IQ Indoor
Nest Cam IQ Outdoor
Nest Cam Outdoor | RTSP
Recording | Motion
Person
Sound | Snapshot (jpg) | @@ -285,8 +287,6 @@ All cameras have motion and person triggers, however only some support capturing | Nest Doorbell (wired, 2nd gen) | WebRTC | Motion
Person
Chime | Clip Preview (mp4, gif) | | Nest Hub Max | RTSP
Recording | Motion
Person
Sound
| Snapshot (jpg) | -Given a camera named `Front Yard` then the camera is created with a name such as `camera.front_yard`. - ## Event @@ -297,14 +297,16 @@ There are two classes of event entities that are available based on the above ca - `motion` for cameras that support any of the event types `camera_motion`, `camera_person`, or `camera_sound` - `doorbell` for all cameras that are doorbells and support `doorbell_chime` events -Nest event entities do not yet expose media for use in attachments. +Nest event entities are updated immediately when an event message is received +without waiting for any media to be fetched. See Device Triggers for media support. ## Device Triggers -## Automation and device triggers - The Nest integration provides [device triggers](/docs/automation/trigger/#device-triggers) to enable automation in Home Assistant. You should review the [Automating Home Assistant](/getting-started/automation/) getting started guide on automations or the [Automation](/docs/automation/) documentation for full details. +Device triggers will wait to fire after any media associated with the event is downloaded. Use an +event entity for immediate notifications without media. + {% my automations badge %} ![Screenshot Device Triggers](/images/integrations/nest/device_triggers.png) @@ -321,13 +323,18 @@ This is an example of what the `nest_event` payload looks like for a Device Trig "type": "doorbell_chime", "timestamp": "2022-01-26T04:56:54.031000+00:00", "nest_event_id": "EXAMPLE_EVENT_ID", + "attachment": { + "image": "/api/nest/event_media/DEVICE_ID/EVENT_ID/thumbnail", + "video": "/api/nest/event_media/DEVICE_ID/EVENT_ID", + } "zones": ["Zone 1"], }, } ``` - `device_id`: The Home Assistant device identifier for the camera -- `nest_event_id`: is an opaque identifier that can be used with the Media Source Attachments described below for supported cameras. +- `nest_event_id`: is an opaque identifier that identifies the event. +- `attachment`: May be present if the device supports snapshots or clips and depends on the device's capabilities. This is a URL where media can be fetched from the media source. - `zones`: Zones triggering the event if available. Zones are configured in the Google Home App, though not supported by all cameras. Events in the area outside of a named zone will be an empty zone name. {% enddetails %} @@ -343,7 +350,7 @@ This feature is enabled by the following permissions: - *Other permissions and notification settings in the Nest or Google Home apps*. {% endnote %} -### Google Home App Notification Settings +## Google Home App Notification Settings The Google Home App Notifications settings control not only which notifications are sent to your phone, but also what gets published to the Pub/Sub feed. @@ -362,7 +369,6 @@ If you are still not getting notifications, you can read this [troubleshooting g {% details "Google Home App Notification Settings" %} - | Google Home App Setting | Notes | | ------------------------ | :---------------------------------------------------------------------: | | Notifications: Push | Required for any detection event to be published | @@ -378,7 +384,7 @@ If you are still not getting notifications, you can read this [troubleshooting g The Nest [media source](/integrations/media_source) platform allows you to browse clips for recent camera events. Home Assistant is not intended to be a Network Video Recorder (NVR) platform, however, basic support for capturing recent events is supported. -The table above describes which devices support event image snapshots or 10-frame mp4 video clips for recent events. +The table above describes which devices support image snapshots or 10-frame mp4 video clips. ### Media Attachments @@ -388,7 +394,7 @@ The Media Source APIs can be used in [Companion App Attachments](https://compani - `/api/nest/event_media/DEVICE_ID/EVENT_ID/thumbnail`: A thumbnail preview of the media, which supports image snapshots (jpg) or clip previews (gif) depending on the camera type. -You can use the event payload fields `device_id` and `event_id` in an [automation](/getting-started/automation/) to send a notification from an [actions](/getting-started/automation-action/) as shown in the examples below. +You can use the Nest Device Trigger payload fields `attachment.image` or `attachment.video`in an [automation](/getting-started/automation/) to send a notification from an [actions](/getting-started/automation-action/) as shown in the examples below. {% details "Example Action: Clip Preview (mp4) attachment for iOS" %} @@ -402,10 +408,8 @@ data: message: Doorbell Pressed title: Someone pressed the doorbell data: - image: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }}/thumbnail - video: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }} + image: {{ trigger.event.data.attachment.image }} + video: {{ trigger.event.data.attachment.video }} mode: single ``` @@ -425,8 +429,7 @@ data: message: Doorbell Pressed title: Someone pressed the doorbell data: - image: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }}/thumbnail + image: {{ trigger.event.data.attachment.image }} ``` {% endraw %} @@ -445,8 +448,7 @@ data: message: Doorbell Pressed title: Someone pressed the doorbell data: - image: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }}/thumbnail + image: {{ trigger.event.data.attachment.image }} ``` {% endraw %}