Termostato

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_id es 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_f o 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:

1. Cambia hvac_mode a cualquier otro valor, excepto eco.
2. Modifica los valores de datos target_temperature apropiados.

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:

1. obtener previous_hvac_mode
2. establecer hvac_mode en el valor previous_hvac_mode
3. confirmar que hvac_mode ya 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 único target_temperature
• Cuando se selecciona el modo Calor • Frío (heat-cool), se establecen dos valores de target_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 training a ready

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_mode se establece en heat-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_mode como off, la palabra "OFF" se muestra en el Nest Thermostat, en el idioma preferido del usuario.
• Cuando hvac_mode se establece en eco, 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:

• locked_temp_min_f
• locked_temp_max_f
• locked_temp_min_c
• locked_temp_max_c

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 true si el Bloqueador solar está habilitado
• sunlight_correction_active: booleano; muestra true si 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; muestra true si 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.