El Nest Learning Thermostat es un dispositivo conectado a Internet que es intuitivo y fácil de usar, y que aprende continuamente sobre los patrones de uso en el hogar para optimizar la comodidad y ahorrar energía. Los usuarios pueden controlar la calefacción y el enfriamiento desde cualquier lugar en el que tengan acceso a una conexión a Internet.
La compatibilidad con estas funciones requiere un sistema de control sofisticado que supere los programas simples basados en puntos de ajuste. Nest ofrece una amplia variedad de algoritmos (como Early On, Radiante real y AirwaveTM) que requieren una cantidad significativa de potencia de procesamiento en comparación con la mayoría de los termostatos. El Nest Thermostat tiene la energía necesaria para proporcionar estas funciones avanzadas.
La API de Nest está diseñada para permitir que los productos controlen el sistema HVAC sin interrumpir los algoritmos de Nest ni sorprender al usuario con comportamientos inesperados. Proporcionan acceso a los siguientes datos del Nest Thermostat:
- Nombre de la estructura y el dispositivo "where name" (ubicación de la casa)
- Etiqueta personalizada del termostato
- Información sobre el estado en línea y la última conexión
- Temperaturas actual y final
- Modo de temperatura
- Temperaturas Eco
- Tiempo para temperatura
- Escala de temperatura (F/C)
- estado de Bloqueo de temperatura y, si está bloqueado, los valores de temperatura bloqueada mínima o máxima
- Duración del temporizador del ventilador y modo HVAC
- Humedad
- Bloqueador solar
Permisos del termostato
Para obtener acceso de lectura a todos los valores de datos de la API del termostato, selecciona el permiso de lectura del termostato para tu cliente.
Para obtener acceso de lectura a todos los valores de datos de la API del termostato y acceso de escritura adicional a los valores seleccionados, selecciona el permiso de lectura/escritura del termostato para tu cliente. Este nivel de permiso te permite actualizar lo siguiente:
- Temperatura final
- Modo HVAC
- Temporizadores del ventilador
A partir de la versión 5 del termostato, también puedes actualizar lo siguiente:
- Escala de temperatura
- Etiqueta de termostato
Identificadores de termostatos
Dispositivo
Los dispositivos Nest se enumeran por tipo como un arreglo de ID, que se puede usar para identificar de forma única un dispositivo a través de la ruta de acceso del dispositivo. Por lo tanto, un ID de termostato de "peyiJNo..." significa que puedes cargar el modelo del dispositivo del termostato en devices/thermostats/peyiJNo... a través de la API.
Cuando un dispositivo se conecta a varios productos, cada desarrollador verá un ID diferente para ese dispositivo. En el caso de un dispositivo que instaló varios productos del mismo desarrollador, este verá el mismo ID.
Nombre
Se proporcionaron dos atributos de nombre. El atributo name más corto se muestra en las etiquetas de la interfaz de usuario, mientras que name_long se usa en el texto largo.
name
En estos ejemplos, name es "Pasillo" o "Pasillo (Oeste)".
name_long
En este ejemplo, name_long es "Office (Planta alta)".
Etiqueta
A partir de la versión de permisos v5, puedes agregar una etiqueta personalizada del termostato a través de la API. En la app de Nest, la etiqueta aparece entre paréntesis, después del nombre de dónde.
A partir de la versión de permisos v6, también puedes leer la etiqueta del termostato.
Ubicación
where_id
- Un identificador único generado por Nest que representa a
name where_ides de solo lectura y se crea de forma automática en la llamada para crear una instancia personalizada.name
Obtén más información sobre los nombres de los termostatos Nest, los Nest Protects y las Nest Cams.
where_name
Cuando eliges cualquiera de los permisos del termostato, puedes acceder al where_name del dispositivo desde el objeto del dispositivo (devices/thermostats).
Otros metadatos
Todos los valores de datos son de solo lectura, a menos que se especifique lo contrario.
| Valor de los datos | Descripción |
|---|---|
locale |
El idioma y el código de país asignados a este dispositivo |
software_version
|
Una string que representa el firmware que está instalado en el dispositivo |
structure_id
|
Una string que representa de forma única esta estructura; es la estructura con la que se sincroniza el dispositivo. |
last_connection
|
La marca de tiempo de la última conexión exitosa con el servicio de Nest |
is_online
|
Estado en línea. Esto lo determina Nest mediante la hora last_connection y una ventana de reconexión esperada específica para el dispositivo. |
Funciones del termostato
Modos del termostato
Los sistemas de HVAC tienen cuatro estados "activados" (heat, cool, heat-cool, eco) y uno "desactivado" (off). Usamos estos estados para administrar la comodidad y el ahorro de energía mediante hvac_mode y los valores de los datos de temperatura.
- Cuando se selecciona el modo Calor o Frío (
heat,cool), el Termostato ajusta la casa a la temperatura final. - Cuando se selecciona el modo Calor • Frío (
heat-cool), el termostato mantendrá la casa cómoda, dentro de un rango de temperatura preferido. - Cuando se seleccionen Temperaturas Eco (eco), el termostato aplicará algoritmos de ahorro de energía para mantener la comodidad de tu casa y reducir el uso de energía. Los termostatos en este modo muestran ECO.
Las estructuras tienen dos estados relacionados con la presencia: En casa o Ausente. Cuando no se detecte movimiento en la casa, la estructura cambiará de En casa a Ausente, y los Termostatos de la casa habilitarán Temperaturas Eco automáticamente.
Cómo funcionan en conjunto los valores de temperatura y hvac_mode
Según el valor de hvac_mode, solo se puede acceder a ciertos valores de datos de temperatura en la API:
| Modo HVAC | Valores de datos de temperatura a los que puedes acceder |
|---|---|
heat o cool |
target_temperature_f o target_temperature_c |
heat-cool
|
target_temperature_low_f y target_temperature_high_f o target_temperature_low_c y target_temperature_high_c |
eco
|
eco_temperature_low_f y eco_temperature_high_fo eco_temperature_low_c y eco_temperature_high_c |
off |
ninguno |
En algunas situaciones, hay reglas especiales para cambiar hvac_mode:
| Situación | ¿Se puede cambiar hvac_mode? |
|---|---|
| El Bloqueo de temperatura está habilitado | Sí |
| El Corte de emergencia está activo | No |
| El calefactor de emergencia está habilitado | No |
El valor de can_cool o can_heat es false |
No |
Temperaturas Eco
Las Temperaturas Eco le permiten al usuario ahorrar energía, ya sea que esté en casa o no.
Considera cambiar la hvac_mode a eco cuando implementes comportamientos de ahorro de energía en tu producto.
Los extremos de temperatura Eco están disponibles en la API de Nest a partir de los permisos de lectura y escritura/lectura/v6 del termostato.
Cómo alternar entre los modos ecológico y no ecológico
Tu producto no debería tener que administrar las temperaturas finales directamente en el modo Eco. Cuando la casa se configura en Ausente, la temperatura final no se muestra, pero se configura internamente, según la selección del usuario. Cuando el termostato se apaga, no se observan temperaturas finales.
Si debes cambiar las temperaturas finales directamente, asegúrate de realizar el cambio en dos llamadas diferentes:
- Cambia
hvac_modea cualquier otro valor, exceptoeco. - Modifica los valores de datos
target_temperatureapropiados.
A partir de los permisos de lectura y escritura de la versión 6 del termostato, puedes acceder a previous_hvac_mode a través de la API para ayudar con las transiciones del modo HVAC.
previous_hvac_mode se usa para almacenar el hvac_mode del dispositivo antes de que pase a "eco".
Por ejemplo, si el Nest Thermostat usa Temperaturas Eco (hvac_mode =
"eco"), previous_hvac_mode está disponible y quieres que tu producto establezca target_temperature, primero debes hacer lo siguiente:
- obtener
previous_hvac_mode - establecer
hvac_modeen el valorprevious_hvac_mode - confirmar que
hvac_modeya no esté configurado en "eco"
Después de seguir estos pasos, establece las temperaturas finales según corresponda.
Según el valor hvac_mode, así es como cambia previous_hvac_mode:
Cuando el estado hvac_mode es... |
Luego, previous_hvac_mode puede ser... |
|---|---|
eco |
heat, cool, heat-cool o off |
heat, cool, heat-cool o off |
vacío/vacío |
Temperatura final
La temperatura final es el valor más importante para el sistema de HVAC, es decir, la temperatura deseada que suele establecer el usuario. La mayoría de las acciones y decisiones se basan en esto. Desde la API, los productos Works with Nest pueden escribir la temperatura final como parte de un proceso más grande.
Siempre se establece una temperatura final cuando el sistema está encendido.
- Cuando se selecciona el modo Calor o Frío (
heat,cool), se establece un únicotarget_temperature - Cuando se selecciona el modo Calor • Frío (
heat-cool), se establecen dos valores detarget_temperature, lo que indica un rango objetivo: uno superior para el enfriamiento y uno inferior para la calefacción. - Cuando se selecciona el modo Eco (
eco), el rango de temperatura de destino se establece internamente
También hay temperaturas de seguridad que impiden la congelación de las tuberías o temperaturas excesivamente altas en la casa.
Cuando el termostato está apagado, no se estableció ninguna temperatura final.
Tiempo para temperatura
El Tiempo para temperatura te da acceso a estos valores de datos para el sistema de HVAC:
time_to_target: El tiempo, en minutos, que tarda la estructura en alcanzar la temperatura final.time_to_target_training- Estado del entrenamiento
- A medida que el termostato aprende cómo responde el sistema de HVAC, ajusta la estimación para alcanzar la temperatura final
- Cuando el termostato esté razonablemente seguro de la hora estimada para alcanzar la temperatura final, el estado cambiará de
trainingaready
Temperatura ambiental
La temperatura medida cerca del termostato Muestra el valor que corresponde con la escala de temperatura preferida del usuario.
Escala de temperatura
Las variables de temperatura ambiente y objetivo se organizan por escala Celsius o Fahrenheit. El atributo temperature_scale será "F" o "C", según la preferencia del usuario. Cada termostato establece esta propiedad, por lo que es posible que, en una sola estructura, un usuario tenga dos termostatos, uno en cada escala de temperatura. Ten en cuenta las preferencias del usuario cuando muestre los valores de temperatura.
A partir de la versión de permisos v5, puedes cambiar la escala de temperatura a través de la API.
Los campos Temperatura ambiente y Objetivo tienen variantes _f y _c para admitir el redondeo coherente cuando se muestran temperaturas.
Pantalla de temperatura
Cuando muestres información sobre la temperatura final, considera estos tres valores dependientes: temperature_scale, hvac_mode y el estado away de la estructura.
Muchos valores de datos trabajan juntos para determinar qué se muestra en la pantalla del Nest Thermostat y cómo se comporta.
- Cuando
hvac_modese establece enheat-cool, el Nest Thermostat muestra los puntos de ajuste bajo y alto separados por un carácter de viñeta (•). De lo contrario, el Nest Thermostat muestra solo la temperatura final - Cuando se configura
hvac_modecomooff, la palabra "OFF" se muestra en el Nest Thermostat, en el idioma preferido del usuario. - Cuando
hvac_modese establece eneco, la palabra "ECO" se muestra en el Nest Thermostat, en el idioma preferido del usuario.
El formato de la temperatura de la pantalla también depende de la escala de temperatura seleccionada (F/C).
Las temperaturas Fahrenheit se muestran como números enteros:
- Temperatura final: 55 °F
- Temperatura ambiente: 18 °C
Las temperaturas Celsius se muestran como un número entero o un valor decimal, con el último dígito establecido en “0.5”:
- Temperatura final: 12 °C
- Temperatura ambiente: 16.5 °C
Hoja
Cuando se muestra el ícono de la hoja en la parte frontal del termostato, este se establece en una temperatura de ahorro de energía y has_leaf = true.
Bloqueo de temperatura
Los usuarios pueden bloquear un Nest Thermostat para que solo se pueda ajustar dentro de un rango de temperatura limitado. A partir de la versión de permisos v5, puedes verificar si la función Bloqueo de temperatura está habilitada. Para ello, marca is_locked. Si es así, lee los valores mínimos y máximos de bloqueo de temperatura a través de la API:
Las temperaturas de bloqueo deben especificarse en pares, como valores máximos y mínimos, y solo se pueden escribir si is_locked = true.
Humedad
Humedad, en porcentaje (%), medida en el dispositivo, redondeada al 5% más cercano.
Bloqueador solar
La tecnología Bloqueador solar ajusta automáticamente la temperatura del Nest Thermostat para compensar los picos de calor que se producen por la luz solar directa en la unidad.
Estos valores de datos te indicarán si el Bloqueador solar está habilitado o si se corrige la temperatura de manera activa.
sunlight_correction_enabled- booleano, muestra
truesi el Bloqueador solar está habilitado
- booleano, muestra
sunlight_correction_active: booleano; muestratruesi el Bloqueador solar está activo, lo que indica que el termostato se encuentra bajo luz solar directa
Ventilador
Muchos sistemas de HVAC tienen ventiladores, lo que significa que el ventilador no se puede controlar de forma independiente. No hay modo de apagado para los ventiladores integrados, ya que el ventilador necesita funcionar cuando la calefacción o el enfriamiento están encendidos.
Sin embargo, si el sistema de HVAC es compatible, se puede activar el ventilador de forma explícita a través de la API para que los ocupantes se sientan más cómodos, sin interactuar con todo el sistema de HVAC.
Si el ventilador se puede controlar de forma independiente, has_fan se establecerá en true y los siguientes valores de datos se podrán configurar con permisos de lectura y escritura del termostato:
fan_timer_active: booleano; muestratruesi el temporizador del ventilador está activo durante un período programado previamente.fan_timer_duration: int, el tiempo (en minutos) que el ventilador está configurado para funcionar
Usa estos valores juntos para iniciar el temporizador del ventilador (encenderlo) durante un período específico. También puedes usar el valor fan_timer_timeout a fin de determinar la marca de tiempo de cuándo se configuró el ventilador para que deje de funcionar.
Ten en cuenta que siempre puedes cambiar fan_timer_duration: es independiente de hvac_mode o del estado de ocupación de la estructura (Ausente).
Puedes esperar estas respuestas si tienes éxito o no:
- 200 OK
- 400 Bad Request
Si el comando para encender el ventilador no produce el resultado esperado, es posible que el ventilador ya esté en funcionamiento (ya sea de forma manual o programada, o debido a un ciclo de calefacción/frío de HVAC).
Límite de frecuencia
Aplicamos límites de frecuencia para protegerte de llamadas excesivas a los dispositivos, que pueden afectar el rendimiento del sistema o la batería. En condiciones normales, los dispositivos Nest cargan la batería con los cables de bajo voltaje del sistema de calefacción y enfriamiento. Sin embargo, si se realizan demasiadas llamadas en un período corto y el nivel de batería se está agotando, el Nest Thermostat desactivará la conexión Wi-Fi para conservar energía.
En la práctica, esto significa que limitamos la cantidad de llamadas que se pueden realizar a un dispositivo dentro de un período definido. Si excedes este límite, recibirás una respuesta de error y un mensaje que indica que lo superaste.
Para obtener más información, consulta Límites de frecuencia de datos.
Limitaciones de alimentación
En algunos casos, es posible que el termostato no tenga suficiente batería para responder a una solicitud de modificación. En este caso, recibirás una respuesta de error y un mensaje que indica que el dispositivo no puede cumplir con la solicitud en este momento. Si esto sucede, espera unos minutos para que se recargue la batería antes de volver a intentarlo.
Obtén más información sobre las condiciones de batería baja en el Nest Learning Thermostat.
Mensajes de error
Algunos estados hacen que algunas funciones no estén disponibles. Estas reglas se utilizan para conservar energía o proporcionar comodidad y seguridad.
Para obtener más información sobre qué significan los errores de llamada a la API y cómo manejarlos, consulta Mensajes de error.
Problema con la conexión Wi-Fi o de conexión
Si un dispositivo no tiene conexión, no se permiten las modificaciones. Puedes observar el estado en línea del dispositivo en el modelo de datos y mostrar la IU de manera adecuada.