O Nest Learning ThermostatTM é um dispositivo conectado à Internet que é intuitivo e fácil de usar, aprendendo constantemente sobre padrões de uso da casa para otimizar o conforto e economizar energia. Os usuários podem controlar o aquecimento e o resfriamento de qualquer lugar que tenham acesso a uma conexão de Internet.
O suporte a esses recursos requer um sistema de controle sofisticado que vá além dos programas simples baseados em setpoint. O Nest fornece uma ampla variedade de algoritmos (como Early On, True Radiant, AirwaveTM) que exigem uma quantidade de energia computacional significativa em comparação com a maioria dos termostatos. O Nest Thermostat tem a potência necessária para fornecer esses recursos avançados.
A API Nest foi criada para permitir que os produtos controlem o sistema HVAC (aquecimento, ventilação e ar-condicionado) sem interromper os algoritmos da Nest nem surpreender o usuário com comportamentos inesperados. Eles dão acesso aos seguintes dados do Nest Thermostat:
- Nome da estrutura e do dispositivo "onde nome" (local na casa)
- Rótulo personalizado do termostato
- Status on-line e informações da última conexão
- Temperaturas atuais e desejadas
- Modo de temperatura
- Temperaturas ecológicas
- Tempo até a temperatura
- Escala de temperatura (conjunto F/C)
- Status de bloqueio de temperatura e, se bloqueado, os valores de temperatura mínima/máxima bloqueada
- Duração do timer do ventilador e modo HVAC (Aquecimento, ventilação e ar-condicionado)
- Umidade
- Filtro solar
Permissões do termostato
Para ter acesso de leitura a todos os valores de dados da API Thermostat, selecione a permissão Termostato de leitura para seu cliente.
Para ter acesso de leitura a todos os valores de dados da API Thermostat e acesso adicional de gravação a valores selecionados, selecione a permissão de Leitura/gravação do Termostato para seu cliente. Esse nível de permissão permite atualizar o seguinte:
- Temperatura-alvo
- Modo HVAC (Aquecimento, ventilação e ar-condicionado)
- Timers de ventilador
A partir da leitura/gravação do termostato v5, também é possível atualizar o seguinte:
- Escala de temperatura
- Etiqueta do termostato
Identificadores do termostato
Dispositivo
Os dispositivos Nest são listados por tipo como uma matriz de IDs, que pode ser usada para
identificar exclusivamente um dispositivo pelo caminho dele. Portanto, um ID de termostato de
"peyiJNo..." significa que você pode carregar o modelo de dispositivo do termostato em
devices/thermostats/peyiJNo... usando a API.
Quando um dispositivo está conectado a vários produtos, cada desenvolvedor vê um ID diferente para ele. Em um dispositivo que tenha instalado vários produtos do mesmo desenvolvedor, o desenvolvedor verá o mesmo ID.
Nome
Dois atributos de nome são fornecidos. O atributo name mais curto é exibido em
rótulos da interface do usuário, enquanto name_long é usado em textos de formato longo.
name
Nesses exemplos, name é "Hallway" ou "Hallway (West)".
name_long
Neste exemplo, name_long é "Office (Upsairs)".
Rótulo
A partir da versão de permissões v5, é possível adicionar um rótulo personalizado do termostato usando a API. No app Nest, o rótulo aparece entre parênteses, após o nome do local.
A partir da versão de permissões v6, também é possível ler o rótulo do termostato.
Onde
where_id
- Um identificador exclusivo gerado pelo Nest que representa
name. where_idé somente leitura e é criado automaticamente na chamada para criar um personalizado em quename.
Saiba mais sobre os nomes de Nest Thermostats, Nest Protects e Nest Cams.
where_name
Quando você escolhe qualquer uma das permissões do
Termostato, você pode
acessar o dispositivo where_name usando o objeto de dispositivo (devices/thermostats).
Outros metadados
Todos os valores de dados são somente leitura, a menos que seja especificado de outra forma.
| Valor dos dados | Descrição |
|---|---|
locale |
O código de idioma e país atribuído a este dispositivo |
software_version
|
Uma string que representa o firmware atualmente instalado no dispositivo. |
structure_id
|
Uma string que representa exclusivamente esta estrutura; é a estrutura com que o dispositivo está pareado |
last_connection
|
O carimbo de data/hora da última conexão bem-sucedida com o serviço do Nest |
is_online
|
Status on-line. Isso é determinado pelo Nest usando o
tempo last_connection e uma janela de reconexão
específica. |
Recursos do termostato
Modos do termostato
Os sistemas HVAC (aquecimento, ventilação e ar-condicionado) têm quatro estados "ativados" (heat, cool, heat-cool e eco) e um
estado "desativado" (off). Usamos esses estados para gerenciar economias de conforto e energia
usando valores de dados de temperatura e hvac_mode.
- Quando o modo de aquecimento ou resfriamento (
heat,cool) é selecionado, o termostato ajusta a casa para a temperatura desejada. - Quando a opção Aquecer • Modo Resfriar (
heat-cool) está selecionada, o termostato mantém a casa confortável, dentro de uma faixa de temperatura preferencial. - Quando Temperaturas econômicas (eco) é selecionada, o termostato aplica algoritmos de economia de energia para manter a casa confortável e reduzir o uso de energia. Os termostatos nesse modo exibem o ECO.
As estruturas têm dois estados relacionados à presença: "Em casa" ou "Ausente". Quando nenhum movimento for detectado na casa, a estrutura vai mudar de "Em casa" para "Ausente", e as termostatos da casa vão ativar as Temperaturas econômicas automaticamente.
Como os valores de hvac_mode e temperatura funcionam juntos
Dependendo do valor de hvac_mode, somente alguns valores de dados de temperatura podem ser acessados na API:
| Modo HVAC (Aquecimento, ventilação e ar-condicionado) | Valores de dados de temperatura que você pode acessar |
|---|---|
heat ou cool |
target_temperature_f ou target_temperature_c |
heat-cool
|
target_temperature_low_f e
target_temperature_high_f ou target_temperature_low_c e
target_temperature_high_c |
eco
|
eco_temperature_low_f e
eco_temperature_high_fou eco_temperature_low_c e
eco_temperature_high_c |
off |
nenhum |
Em alguns cenários, há regras especiais sobre como mudar hvac_mode:
| Cenário | hvac_mode pode ser alterado? |
|---|---|
| O bloqueio de temperatura está ativado | Sim |
| O desligamento de emergência está ativo. | Não |
| O aquecimento de emergência está ativado. | Não |
O valor de can_cool ou can_heat é false |
Não |
Temperaturas econômicas
As Temperaturas econômicas permitem que o usuário economize energia, seja em casa ou não.
Mude a hvac_mode para eco ao implementar comportamentos de economia
de energia no seu produto.
Os endpoints de temperatura econômica estão disponíveis na API Nest a partir das permissões de leitura e gravação v6 do termostato.
Como alternar entre os modos econômico e não econômico
Seu produto não precisa gerenciar as temperaturas desejadas diretamente no modo Eco. Quando a casa está definida como ausente, a temperatura desejada não é exibida, mas é definida internamente, com base na seleção do usuário. Quando o termostato estiver desativado, nenhuma temperatura-alvo será observada.
Se for necessário mudar as temperaturas desejadas diretamente, faça a mudança em duas chamadas separadas:
- Mude
hvac_modepara qualquer outro valor, excetoeco. - Modifique os valores de dados
target_temperatureadequados
Começando com as permissões de leitura e gravação/gravação do termostato v6, é possível acessar
previous_hvac_mode pela API para ajudar nas transições do modo HVAC (aquecimento, ventilação e ar-condicionado).
previous_hvac_mode é usado para armazenar o hvac_mode do dispositivo antes da
transição para "eco".
Por exemplo, se o Nest Thermostat estiver usando Temperaturas econômicas (hvac_mode =
"eco"), previous_hvac_mode estiver disponível e você quiser que seu produto defina target_temperature, primeiro:
- receba
previous_hvac_mode - Defina
hvac_modecom o valorprevious_hvac_mode - confirme se
hvac_modenão está mais definido como "eco".
Após estas etapas, defina as temperaturas desejadas conforme apropriado.
Dependendo do valor de hvac_mode, o previous_hvac_mode vai mudar da seguinte forma:
Quando o estado hvac_mode é... |
Então, previous_hvac_mode pode ser... |
|---|---|
eco |
heat, cool, heat-cool ou off |
heat, cool, heat-cool ou off |
em branco/vazio |
Temperatura-alvo
A temperatura desejada é o valor mais importante para o sistema HVAC (aquecimento, ventilação e ar-condicionado). Essa é a temperatura desejada, geralmente definida pelo usuário. A maioria das ações e decisões é baseada nelas. Usando a API, os produtos Works with Nest podem gravar a temperatura-alvo como parte de um processo maior.
Sempre há uma temperatura desejada definida quando o sistema está ligado.
- Quando o modo de aquecimento ou resfriamento (
heat,cool) é selecionado, apenas umtarget_temperatureé definido. - Quando a opção Aquecer • Modo Resfriar (
heat-cool) está selecionada, dois valorestarget_temperaturesão definidos, indicando uma faixa de segmentação, uma superior para a de resfriamento e uma inferior para o aquecimento. - Quando o modo Eco (
eco) é selecionado, a faixa de temperatura desejada é definida internamente
Há também temperaturas de segurança que são um ponto de parada para evitar o travamento de tubulações ou temperaturas excessivamente altas na casa.
Quando o termostato estiver desativado, nenhuma temperatura desejada será definida.
Tempo até a temperatura desejada
O tempo até a temperatura dá acesso a estes valores de dados para o sistema HVAC (aquecimento, ventilação e ar-condicionado).
time_to_target: o tempo, em minutos, que leva para que a estrutura alcance a temperatura desejadatime_to_target_training- Status do treinamento
- À medida que o termostato aprende como o sistema HVAC (aquecimento, ventilação e ar-condicionado) responde, ele ajusta a estimativa para alcançar a temperatura desejada.
- Quando o termostato tiver certeza da estimativa de tempo para alcançar a
temperatura desejada, o status mudará de
trainingparaready
Temperatura ambiente
A temperatura medida perto do termostato. Exiba o valor correspondente à escala de temperatura preferencial do usuário.
Escala de temperatura
As variáveis de temperatura ambiente e de destino são organizadas por escala de Celsius ou Fahrenheit. O atributo temperature_scale será "F" ou "C",
dependendo da preferência do usuário. Essa propriedade é definida por cada termostato, portanto, é
possível que, em uma única estrutura, o usuário possa ter dois termostatos, um em
cada escala de temperatura. Lembre-se das preferências
do usuário ao
exibir valores de temperatura.
A partir da versão de permissões v5, é possível alterar a escala de temperatura por meio da API.
Os campos de objetivo e de temperatura ambiente têm variantes _f e _c para acomodar
um arredondamento consistente ao exibir temperaturas.
Exibição de temperatura
Ao exibir informações de temperatura-alvo, considere estes três valores dependentes: temperature_scale, hvac_mode e o estado away da estrutura.
Muitos valores de dados funcionam juntos para determinar o que é mostrado na tela do Nest Thermostat e como ele se comporta.
- Quando
hvac_modeé definido comoheat-cool, o Termostato Nest mostra as temperaturas mínimas e altas separadas por um caractere de marcador (•). Caso contrário, o Nest Thermostat exibirá somente a temperatura desejada. - Quando
hvac_modeé definido comooff, a palavra "DESATIVADO" é exibida no Termostato Nest, no idioma preferido do usuário. - Quando
hvac_modeé definido comoeco, a palavra "ECO" é exibida no Nest Termostato, no idioma preferido do usuário.
O formato de temperatura da tela também depende da escala de temperatura selecionada (F/C).
As temperaturas em Fahrenheit são exibidas como números inteiros:
- Temperatura-alvo: 10°C
- Temperatura ambiente: 62 °F
As temperaturas em Celsius são exibidas como um número inteiro ou um valor decimal, com o último dígito definido como ".5":
- Temperatura-alvo: 12°C
- Temperatura ambiente: 16,5 °C
Folha
Quando o ícone de folha é mostrado na parte da frente do termostato, ele é
configurado para uma temperatura de economia de energia e has_leaf = true.
Trava de temperatura
Os usuários podem bloquear um Nest Thermostat para que ele só possa ser ajustado dentro de uma
faixa de temperatura limitada. A partir da versão de permissões
v5, é possível ver
se o Bloqueio de
temperatura está ativado
verificando
is_locked. Se estiver,
leia os valores mínimo/máximo de Bloqueio de temperatura pela API:
As temperaturas de bloqueio precisam ser especificadas em pares, como valores máximos e mínimos, e
só podem ser gravadas se is_locked = true.
Umidade
Umidade, no formato de porcentagem (%), medida no dispositivo, arredondada para o valor de 5% mais próximo.
Filtro solar
A tecnologia Filtro solar ajusta automaticamente a temperatura do Nest Thermostat para compensar os picos de calor causados pela luz solar direta na unidade.
Esses valores informam se o Filtro solar está ativado e/ou corrigir a temperatura ativamente.
sunlight_correction_enabled- booleano, retornará
truese o Filtro solar estiver ativado
- booleano, retornará
sunlight_correction_active: booleano, retornatruese o Filtro solar estiver ativo, indicando que o Termostato está localizado sob luz solar direta.
Ventilador
Muitos sistemas HVAC (aquecimento, ventilação e ar-condicionado) têm ventiladores integrados, o que significa que o ventilador não pode ser controlado de forma independente. Não há modo de desativação para fãs integrados, porque o ventilador precisa funcionar quando o aquecimento ou o resfriamento está ativado.
No entanto, se o sistema HVAC (aquecimento, ventilação e ar-condicionado) for compatível, será possível ativar o ventilador explicitamente pela API para deixar os ocupantes mais confortáveis, sem que seja necessário ativar o sistema completo.
Se o ventilador puder ser controlado de forma independente, o has_fan será definido como true, e
os seguintes valores de dados poderão ser definidos com as permissões de leitura/gravação do termostato:
fan_timer_active: booleano, retornatruese o timer de ventilador estiver engajado por uma duração pré-programadafan_timer_duration: o tempo (em minutos) em que a ventilação será definida para execução
Use esses valores juntos para iniciar o timer do ventilador (ativar o ventilador) por um
período específico. Também é possível usar o valor
fan_timer_timeout
para determinar o carimbo de data/hora em que o ventilador está configurado para parar de ser executado.
É possível mudar o fan_timer_duration a qualquer momento. Ele é independente do
hvac_mode ou do estado de ocupação da estrutura (distância).
Você pode esperar estas respostas:
- 200 OK
- 400 Solicitação inválida
Se o comando para ligar o ventilador não produzir o resultado esperado, pode ser porque ele já está engajado (manualmente pelo usuário ou em uma programação ou por um ciclo de aquecimento/resfriamento HVAC).
Limitação de taxa
Aplicamos a limitação de taxa para proteger contra o excesso de chamadas para os dispositivos, o que pode afetar o desempenho do sistema ou da bateria. Em condições normais, os dispositivos Nest carregam a bateria a partir dos fios de baixa tensão do sistema de aquecimento e resfriamento. No entanto, se chamadas em excesso forem feitas em um curto período de tempo e o nível da bateria estiver baixo, o Nest Thermostat vai desativar o Wi-Fi para economizar energia.
Na prática, isso significa que limitamos o número de chamadas que podem ser feitas para um dispositivo em um período definido. Se exceder esse limite, você vai receber uma resposta de erro e uma mensagem indicando que isso foi feito.
Para mais informações, consulte Limites de taxa de dados.
Restrições de energia
Em alguns casos, o termostato pode não ter bateria suficiente para atender a uma solicitação de modificação. Nesse caso, você receberá uma resposta de erro e uma mensagem indicando que o dispositivo não consegue atender à solicitação no momento. Se isso acontecer, dê algum tempo para recarregar a bateria antes de tentar novamente.
Saiba mais sobre condições de bateria fraca no Nest Learning Thermostat.
Mensagens de erro
Alguns estados tornam determinadas funções indisponíveis. Essas regras estão em vigor para preservar energia ou fornecer conforto e segurança.
Para mais informações sobre o que significam erros de chamada de API e como lidar com eles, consulte Mensagens de erro.
Problema de conexão Wi-Fi / conexão
Se um dispositivo estiver off-line, as modificações não serão permitidas. É possível observar o estado on-line do dispositivo no modelo de dados e exibir a IU corretamente.