From ae571bbc840e44c68a4d21a7a8a59bdd373a9b54 Mon Sep 17 00:00:00 2001
From: Jason Hu <awarecan@users.noreply.github.com>
Date: Sun, 17 Jun 2018 22:57:53 -0700
Subject: [PATCH] Add eta for nest.set_mode service, add security_state to
 sensor.nest (#5518)

---
 source/_components/nest.markdown        | 23 ++++++++++++++++++++++-
 source/_components/sensor.nest.markdown | 24 ++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/source/_components/nest.markdown b/source/_components/nest.markdown
index e5fd06a0c9a..a6e021b94fa 100644
--- a/source/_components/nest.markdown
+++ b/source/_components/nest.markdown
@@ -65,7 +65,15 @@ Configuration variables:
 
 Currently there is a single `nest.set_mode` service available to switch between
 "away" and "home" modes. This service requires a `home_mode` param and has an
-optional `structure` param.
+optional `structure` param. While setting "away" mode, an estimated arrival time
+can also be set with `eta`, `eta_window`, and `trip_id` parameters.
+
+- **home_mode** (*Required*): `home` or `away`
+- **structure** (*Optional*): Structure(s). Default apply to all structures connected with Home Assistant.
+- **eta** (*Optional*): Estimated Time of Arrival from now.
+- **eta_window** (*Optional*): ETA window (default is 1 minute).
+- **trip_id** (*Optional*): Unique ID for the trip. Using an existing trip ID will update that trip's ETA.
+
 
 ```yaml
 # Example script to set away, no structure specified so will execute for all
@@ -86,3 +94,16 @@ set_nest_home:
         structure:
           - Building
 ```
+
+```yaml
+# Example script to set eta, structure specified
+set_nest_eta:
+  sequence:
+    - service: nest.set_mode
+      data:
+        home_mode: away
+        structure:
+          - Building
+        eta: 00:10:30
+        eta_window: 00:05
+```
diff --git a/source/_components/sensor.nest.markdown b/source/_components/sensor.nest.markdown
index 36cf55bd03d..a0db2789118 100644
--- a/source/_components/sensor.nest.markdown
+++ b/source/_components/sensor.nest.markdown
@@ -20,6 +20,8 @@ The `nest` sensor platform lets you monitor sensors connected to your [Nest](htt
 You must have the [Nest component](/components/nest/) configured to use these sensors. The sensors will be setup if the `nest` component is configured and the required configuration for the `nest sensor` is set.
 </p>
 
+## {% linkable_title Configuration %}
+
 To enable sensors and customize which sensors are setup, you can extend the [Nest component](/components/nest/) configuration in your `configuration.yaml` file with the following settings:
 ```yaml
 # Example configuration.yaml entry
@@ -40,6 +42,7 @@ The following conditions are available by device:
 
 - Nest Home:
   - eta: Estimated time of arrival.
+  - security\_state: `ok` or `deter`. [Security State](#security-state)
 - Nest Thermostat:
   - humidity
   - operation\_mode
@@ -53,3 +56,24 @@ The following conditions are available by device:
   - color\_status: `gray`, `green`, `yellow`, or `red`. Indicates device status by color in the Nest app UI. It is an aggregate condition for battery+smoke+CO states, and reflects the actual color indicators displayed in the Nest app.
 - Nest Camera: none
 
+## {% linkable_title Security State %}
+
+<p class='note warning'>
+This feature is not designed to transfer your Home Assitant to a secruity system, neither Home Assistant nor Nest be liable to You for damages,
+or consequential damages of any character arising as a result of use this feature.
+  
+This feature does not depend on the [Nest Secure alarm system](https://nest.com/alarm-system/overview/) and is not a reflection of the status of that system,
+nor does it react to state changes in that system.
+</p>
+
+<p class='note'>
+This feautre use a new [Nest Secruity API](https://developers.nest.com/documentation/cloud/security-guide),
+you may need to change your ["Product"](https://developers.nest.com/products) permission setting to include `Secruity State Read`.
+After permission change, you may need to re-authorize your client.
+</p>
+
+If a Nest Cam detects the presence of a person (see `person_detected` in [binary_sensor.nest](/components/binary_sensor.nest/)) while the structure is in `away` mode (see `away` in [binary_sensor.nest](/components/binary_sensor.nest/)), the structure enters `deter` mode.
+
+A `deter` state is re-evaluated after several minutes and relaxed to `ok` if no further `person_detected` events have occurred.
+
+The `security_state` automatically switches to `ok` when the structure state is `home`.