En la API de Nest, el concepto de En casa o Ausente tiene un efecto poderoso en los comportamientos de las funciones de ahorro de energía y conveniencia de Nest.
Cómo funcionan las rutinas En casa y Ausente
Nest usa una variedad de indicadores para detectar la presencia humana en una casa. Si Nest no detecta presencia durante un período prolongado, establece automáticamente el modo Ausente en la casa. Cuando detecta presencia humana, revierte la estructura al estado Home.
Si reaccionas a los cambios en el estado En casa/Ausente, se abre una amplia variedad de oportunidades para tus productos. Por ejemplo, sus productos pueden hacer lo siguiente:
- Apaga las luces cuando se active el modo Ausente para ahorrar energía
- Enviar una notificación si la puerta de la cochera está abierta cuando la casa está ausente
- Reproduce música cuando la casa cambia a En casa
Cómo funciona la hora de llegada estimada
En algunos casos, los usuarios tienen una app de terceros que usa GPS para proporcionar los datos de hora de llegada estimada (ETA) a la API de Nest. En otros casos, el usuario podría usar una app para ingresar manualmente la hora de llegada estimada. También es posible que la hora de llegada se calcule según el horario regular del usuario.
Las apps de ETA integradas en el Nest Thermostat hacen que el termostato comience a calentar o enfriar la casa antes de que llegue el usuario.
Cuando existe la integración de hora de llegada/termostato en la cuenta del usuario, los datos de ETA están disponibles para que otros desarrolladores de Works with Nest los usen en sus integraciones de Works with Nest.
Después de ingresar la hora de llegada estimada al servicio de Nest, otra integración de Works with Nest puede usarla como señal para preparar la casa a fin de que llegue el usuario.
- La hora de llegada estimada la escribe un desarrollador de Nest mediante la llamada a la API
de
PUT etade solo escritura. - El Nest Thermostat usa estos datos.
- Si otros desarrolladores también quieren usarla, pueden usar la llamada a la API de
GET eta_beginde solo lectura.
El punto importante a tener en cuenta es que los datos de hora de llegada deben ser ingresados por un tercero. Actualmente, Nest no proporciona datos de hora de llegada estimada. Si no se escriben los datos de la hora de llegada estimada, la API de Nest muestra el valor predeterminado "1970-01-01T00:00:00.000Z"
Supongamos, por ejemplo, que usted es un proveedor de iluminación. Puedes obtener los datos de ETA proporcionados por la integración de ETA/termostato y usarlos como señal para encender las luces.
De esta forma, no solo la temperatura es cómoda, las luces también están encendidas cuando el usuario llega a la casa.
Si reaccionas a los cambios en el estado de hora de llegada, se abrirá una amplia variedad de oportunidades para tus productos. Por ejemplo, sus productos pueden hacer lo siguiente:
- Encender la TV cuando el usuario se acerque a la casa
- Abre la puerta de la cochera cuando el usuario esté por llegar a casa
- Reproducir música cuando el usuario vuelve a la casa
Permisos de Ausente
Los siguientes niveles de permiso de acceso están disponibles para los valores de datos relacionados con la función Ausente:
Acceso |
Lectura fuera de casa Lectura y escritura en modo Ausente |
Hora de llegada estimada |
Lectura y escritura en ETA |
alarma de humo + monóxido de carbono |
Lectura en el termostato Lectura/escritura del termostato |
|---|---|---|---|---|---|
away |
Sí | Sí | Sí | ||
eta_begin (solo lectura) |
Sí | Sí | |||
Objeto eta (solo escritura) |
Sí |
Para obtener más información, consulta la Descripción general de permisos.
Funciones Ausente
En casa y Ausente
El valor de los datos de away puede indicarte si Nest cree que la estructura está ocupada. Los siguientes son los valores posibles:
| Valor | Descripción |
|---|---|
home | Hay alguien en la estructura. Este estado se puede configurar: • Nest si tiene una alta confianza a partir de los datos de los sensores de movimiento • del usuario mediante la app de Nest, el Nest Thermostat o tu producto algorítmico • Algoritmo por ETA |
away | No hay nadie en la estructura. El usuario desactivó explícitamente la estructura en la app de Nest, el Nest Thermostat o tu producto. |
unknown | Si no hay dispositivos asociados con la estructura, el estado ausente es unknown. |
La API de Nest ofrece la capacidad de establecer directamente los modos En casa y Ausente, así como detectar cambios en estos estados. Sin embargo, cuando se configura En casa y Ausente, se debe hacer de la misma manera que la app de Nest: como resultado de una solicitud explícita del usuario. Si se intenta establecer este estado de manera algorítmica, se corre el riesgo de crear una experiencia del usuario confusa, y está prohibido por las políticas de diseño de Nest.
Ten en cuenta que los usuarios siempre tienen la capacidad de establecer manualmente el estado En casa/Ausente.
Obtén más información sobre cómo los usuarios establecen los estados de En casa y Ausente.
ETA
La ETA es un objeto con campos que se pueden configurar en una estructura. Se usa para avisarle a Nest que se espera que un usuario regrese a casa en un momento específico. Cuando se configura la hora de llegada estimada, un producto genera un trip_id único y proporciona un período de llegada previsto, especificado por los siguientes valores:
estimated_arrival_window_beginestimated_arrival_window_end
Debido a que las circunstancias de los viajes pueden cambiar debido al tráfico, los planes de usuarios modificados y otros eventos, los productos deben actualizar la hora de llegada estimada periódicamente a medida que el viaje avanza. Esto proporciona a Nest un flujo de horas de llegada estimadas (5 minutos es un intervalo ideal).
Cuanta más información recibimos, más seguros podemos estar de la confiabilidad de las entradas de ETA, lo que nos hace más seguros a la hora de tomar medidas para preparar la casa.
La hora de llegada es independiente del estado de origen. Si la hora de llegada de una hora de llegada entra en conflicto con otra, tiene prioridad la hora de llegada más antigua.
Cómo realizar una llamada de escritura en hora estimada de llegada
La lógica de ETA depende de la presencia de un termostato en la estructura. Si no existe un termostato en la estructura, las llamadas realizadas al objeto ETA fallarán y se mostrará el mensaje de error No hay dispositivos vinculados. Este error ocurre incluso si existen otros tipos de dispositivos en la estructura (por ejemplo, una Nest Cam o un Nest Protect).
Valores de datos
Una llamada de ETA requiere los siguientes valores de datos:
| Nombre | Tipo | Descripción |
|---|---|---|
trip_id |
string | Identificador único de viaje de ETA |
estimated_arrival_window_begin |
string | Marca de tiempo Debe ser mayor que NOW, en formato ISO 8601. |
estimated_arrival_window_end |
string | Marca de tiempo Debe ser mayor que estimated_arrival_window_begin, en formato ISO 8601. |
Debido a la posibilidad de los bloqueos de conexión en las comunicaciones de GPS, te sugerimos un flujo de muestras, idealmente una vez cada 5 minutos.
Cada llamada de ETA debe incluir una string única de trip_id que definas en la llamada inicial. Otros parámetros pueden cambiar con llamadas sucesivas al mismo trip_id.
Una llamada de ETA muestra un código de estado HTTP 200 OK cuando se realiza correctamente.
Examples
curl --location-trusted -X PUT -d \
'{"trip_id":"sample-trip-id","estimated_arrival_window_begin":"2014-10-31T22:42:00.000Z","estimated_arrival_window_end":"2014-10-31T23:59:59.000Z"}' \
"http://developer-api.nest.com/structures/5af48890-b516-11e3-9eff-123139166438/eta.json?auth=c.VG6bfzyOxAltaih6P4v..."
Cómo cancelar una hora de llegada estimada
Para cancelar la hora de llegada estimada, envía estimated_arrival_window_begin = 0. Verifica que envíes un número entero (0) en esta llamada, no una string (0); de lo contrario, la llamada fallará.
Mensajes de error
Para obtener información sobre el significado de los errores de llamada a la API y cómo manejarlos, consulta Mensajes de error.