From 573dd42d891c200875a06c96308f01beebf43f6d Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Wed, 26 Jan 2022 01:15:43 -0800 Subject: [PATCH] Update documentation for nest Media Source attachments (#21337) --- source/_integrations/nest.markdown | 126 ++++++++++++++++++++++------- 1 file changed, 98 insertions(+), 28 deletions(-) diff --git a/source/_integrations/nest.markdown b/source/_integrations/nest.markdown index 45d74ef25e0..75a38df640a 100644 --- a/source/_integrations/nest.markdown +++ b/source/_integrations/nest.markdown @@ -320,7 +320,7 @@ All cameras have motion and person triggers, however only some support capturing | 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) | | Nest Cam with floodlight | WebRTC | Motion
Person | N/A | -| Nest Doorbell (battery) | WebRTC | Motion
Person
Chime | Clip Preview (mp4) | +| Nest Doorbell (battery) | WebRTC | Motion
Person
Chime | Clip Preview (mp4, gif) | | Nest Doorbell (wired) | RTSP
Recording | Motion
Person
Sound
Chime | Snapshot (jpg) | | Nest Hub Max | RTSP
Recording | Motion
Person
Sound
* [SDM API known issue](https://github.com/home-assistant/core/issues/58482) | Snapshot (jpg) | @@ -329,13 +329,35 @@ Given a camera named `Front Yard` then the camera is created with a name such as ## Automation and Device Triggers -The Nest integration makes [device triggers](/docs/automation/trigger/#device-triggers) available 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. +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. {% my automations badge %} ![Screenshot Device Triggers](/images/integrations/nest/device_triggers.png) +{% details "Example Device Trigger / Event payload %} + +This is an example of what the `nest_event` payload looks like for a Device Trigger that you can use to power automations. + +```json +{ + "event_type": "nest_event", + "data": { + "device_id": "EXAMPLE_DEVICE_ID", + "type": "doorbell_chime", + "timestamp": "2022-01-26T04:56:54.031000+00:00", + "nest_event_id": "EXAMPLE_EVENT_ID", + }, +} +``` + +* `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. + +{% enddetails %} + +Continue reading below to *Media Source Attachments* to see how to use media with notification actions. +
This feature is enabled by the following permissions: @@ -345,37 +367,85 @@ This feature is enabled by the following permissions: - *Other permissions in the Nest or Google Home apps*.
- -## Example - -This automation will trigger when a `nest_event` event type with a type of `camera_motion` is received from the specified `device_id`. - -```yaml -alias: "motion alert" -trigger: - - platform: event - event_type: nest_event - event_data: - device_id: YOUR_DEVICE_ID - type: camera_motion -action: - - service: notify.mobile_app_pixel_2 - data: - title: motion detected - message: front door motion detected - data: - image: /api/camera_proxy/camera.front_door -``` - -The action in this section uses the [Android Companion App](https://companion.home-assistant.io/docs/notifications/notifications-basic/) and the camera proxy to send a notification with a snapshot from the camera. - - ## Media Source 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. +### Media Attachments + +The Media Source APIs can be used in [Companion App Attachments](https://companion.home-assistant.io/docs/notifications/notification-attachments) for Notifications as actions for Device Triggers above like *Doorbell Pressed*. You will need to be familiar with both the Media Sources supported for your camera, as well as the media capabilities of the companion apps. + +* `/api/nest/event_media/DEVICE_ID/EVENT_ID`: Media for the event, which supports image snapshots (jpg) or clip previews (mp4) depending on the camera type. + +* `/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. + +{% details "Example Action: Clip Preview (mp4) attachment for iOS %} + +Example for cameras that support Clip Previews used with iOS which can render video in notifications. + +{% raw %} + +```yaml +service: notify.mobile_app_iphone +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 }} +mode: single +``` + +{% endraw %} + +{% enddetails %} + +{% details "Example Action: Clip Preview thumbnail (gif) for Android or iOS %} + +Example for cameras that support Clip Previews, but transcoded to an animated gif (Android does not render video notifications). + +{% raw %} + +```yaml +service: notify.mobile_app_android +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 +``` + +{% endraw %} + +{% enddetails %} + +{% details "Example Action: Snapshot (jpg) attachment for Android or iOS %} + +Example for cameras that support Snaphot (jpg) on either Android or iOS. + +{% raw %} + +```yaml +service: notify.mobile_app +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 +``` + +{% endraw %} + +{% enddetails %} +
This feature is enabled by the following permissions: