O Nest Learning Thermostat ™ é um dispositivo conectado à Internet que é intuitivo e fácil de usar, aprendendo continuamente sobre os padrões de uso em casa para otimizar o conforto e economizar energia. Os usuários podem controlar o aquecimento e o resfriamento em qualquer lugar com acesso à Internet.
O suporte a esses recursos requer um sistema de controle sofisticado que vai além dos simples programas baseados em pontos de ajuste. O Nest fornece uma ampla gama de algoritmos (como Early On , True Radiant , Airwave ™ ) que requerem uma quantidade significativa de potência computacional em comparação com a maioria dos termostatos. O Nest Thermostat tem a energia necessária para fornecer esses recursos avançados.
A API Nest foi projetada para permitir que os produtos controlem o sistema HVAC sem interromper os algoritmos Nest ou surpreender o usuário com comportamentos inesperados. Eles fornecem acesso aos seguintes dados para o Nest Thermostat:
- Nome da estrutura e dispositivo "onde nome" (localização na casa)
- Etiqueta de termostato personalizada
- Status online e última informação de conexão
- Temperatura atual e alvo
- Modo de temperatura
- Eco temperaturas
- Tempo para temperatura
- Escala de temperatura (definir F / C)
- Status do bloqueio de temperatura e, se bloqueado, os valores de temperatura mínima / máxima bloqueados
- Duração do temporizador do ventilador e modo HVAC
- Umidade
- Protetor solar
Permissões de termostato
Para acesso de leitura a todos os valores de dados da API do termostato, selecione a permissão de leitura do termostato para seu cliente.
Para acesso de leitura a todos os valores de dados da API do termostato e acesso de gravação adicional para selecionar valores, selecione a permissão de leitura / gravação do termostato para seu cliente. Este nível de permissão permite que você atualize o seguinte:
- Temperatura alvo
- Modo HVAC
- Fan timers
A partir do termostato de leitura / gravação v5, você também pode atualizar o seguinte:
- Escala de temperatura
- Rótulo do termostato
Identificadores de termostato
Dispositivo
Os dispositivos Nest são listados por tipo como uma série de IDs, que podem ser usados para identificar exclusivamente um dispositivo por meio do caminho do dispositivo. Portanto, uma ID de termostato de "peyiJNo..." significa que você pode carregar o modelo do devices/thermostats/peyiJNo... em devices/thermostats/peyiJNo... por meio da API.
Quando um dispositivo é conectado a vários produtos, cada desenvolvedor verá um ID diferente para aquele dispositivo. Para um dispositivo que instalou vários produtos do mesmo desenvolvedor, o desenvolvedor verá o mesmo ID.
Nome
Dois atributos de nome são fornecidos. O atributo de name mais curto é exibido nos rótulos da interface do usuário, enquanto name_long é usado em texto de formato longo.
name
Nestes exemplos, o name é "Corredor" ou "Corredor (Oeste)".
name_long
Neste exemplo, name_long é "Office (Upstairs)".
Rótulo
Começando com as permissões da versão v5 , você pode adicionar um rótulo de termostato personalizado por meio da API. No app Nest, o rótulo aparece entre parênteses, após o nome where.
Começando com as permissões da versão v6 , você também pode ler o rótulo do termostato.
Onde
where_id
- Um identificador exclusivo gerado pelo Nest que representa o
name -
where_idé somente leitura e é criado automaticamente na chamada para criar umnamewhere personalizado
Saiba mais sobre os nomes dos termostatosNest ,Nest Protects e Nest Cams .
where_name
Ao escolher qualquer uma das permissões do termostato , você pode acessar o dispositivo where_name partir do objeto dispositivo ( devices/thermostats ).
Outros metadados
Todos os valores de dados são somente leitura, a menos que seja especificado de outra forma.
| Valor de Dados | Descrição |
|---|---|
locale | O idioma e o código do país atribuídos a este dispositivo |
software_version | Uma string que representa o firmware atualmente instalado no dispositivo |
structure_id | Uma string que representa exclusivamente esta estrutura; esta é a estrutura com a qual o dispositivo está emparelhado |
last_connection | O carimbo de data / hora da última conexão bem-sucedida com o serviço Nest |
is_online | Status online. Isso é determinado pelo Nest usando o tempo de last_connection e uma janela de reconexão esperada que é específica do dispositivo. |
Recursos do termostato
Modos de termostato
Os sistemas HVAC têm quatro estados "ligado" ( heat , cool , heat-cool , eco ) e um estado "desligado" ( off ). Usamos esses estados para gerenciar conforto e economia de energia por meio de hvac_mode e valores de dados de temperatura.
- Quando o modo Calor ou Frio (
heat,cool) é selecionado, o termostato ajusta a casa para a temperatura desejada. - Quando o modo Calor • Frio (
heat-cool) é selecionado, o termostato manterá a casa confortável, dentro de uma faixa de temperatura preferida. - Quando Eco Temperatures (eco) é selecionado, o termostato aplicará algoritmos de economia de energia para manter a casa confortável e reduzir o uso de energia. Os termostatos neste modo exibem ECO.
As estruturas têm dois estados relacionados à presença: Casa ou Fora. Quando nenhum movimento for detectado na casa, a estrutura mudará de Casa para Fora e os termostatos da casa habilitarão as temperaturas ecológicas automaticamente.
Como os valores de hvac_mode e temperatura funcionam juntos
Dependendo do valor de hvac_mode , apenas determinados valores de dados de temperatura podem ser acessados na API:
| Modo HVAC | 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_fou 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, existem regras especiais sobre como alterar hvac_mode :
| Cenário | O hvac_mode pode ser alterado? |
|---|---|
| O bloqueio de temperatura está ativado | sim |
| O desligamento de emergência está ativo | Não |
| Calor de emergência está habilitado | Não |
can_cool valor can_cool ou can_heat é false | Não |
Eco temperaturas
As temperaturas ecológicas permitem ao usuário economizar energia, esteja ou não em casa. Considere mudar o hvac_mode para eco ao implementar comportamentos de economia de energia em seu produto.
Os endpoints de Eco Temperatura estão disponíveis na API Nest, começando com as permissões de leitura e leitura / gravação do termostato v6.
Alternando entre os modos eco e não eco
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 é definido como DESLIGADO, nenhuma temperatura alvo é observada.
Se você absolutamente deve alterar as temperaturas alvo diretamente, certifique-se de fazer a alteração em duas chamadas separadas:
- Altere
hvac_modepara qualquer outro valor, excetoeco - Modifique os valores de dados
target_temperatureapropriados
Começando com as permissões de leitura e leitura / gravação do termostato v6, você pode acessar previous_hvac_mode por meio da API para auxiliar nas transições de modo HVAC. previous_hvac_mode é usado para armazenar o hvac_mode do dispositivo antes de fazer a transição para "eco".
Por exemplo, se o Nest Thermostat estiver usando Eco Temperatures ( hvac_mode = "eco" ), previous_hvac_mode está disponível e você deseja que seu produto defina target_temperature , então você deve primeiro:
- obter
previous_hvac_mode - defina
hvac_modepara o valorprevious_hvac_mode - confirme que
hvac_modenão está mais definido como "eco"
Após essas etapas, defina as temperaturas desejadas conforme apropriado.
Dependendo do valor de hvac_mode , é assim que o previous_hvac_mode muda:
Quando o estado hvac_mode é ... | Então, previous_hvac_mode pode ser ... |
|---|---|
eco | heat , cool , heat-cool ou off |
heat , cool , cool heat-cool ou off | em branco / vazio |
Temperatura alvo
A temperatura desejada é o valor mais importante para o sistema HVAC - é a temperatura desejada, normalmente definida pelo usuário. A maioria das ações e decisões são baseadas nele. A partir da API, os produtos Works with Nest podem gravar a temperatura desejada como parte de um processo maior.
Sempre há uma temperatura-alvo definida quando o sistema está ligado.
- Quando o modo Calor ou Frio (
heat,cool) é selecionado, um únicotarget_temperatureé definido - Quando o modo Calor • Resfriar (
heat-cool) é selecionado, dois valores detarget_temperaturesão definidos, denotando um intervalo alvo, um mais alto para resfriamento e um mais baixo para aquecimento - Quando o modo Eco (
eco) é selecionado, a faixa de temperatura alvo é definida internamente
Existem também temperaturas de segurança que são uma barreira para evitar o congelamento de canos ou temperaturas excessivamente altas em casa.
Quando o termostato está desligado, nenhuma temperatura alvo é definida.
Tempo para temperatura
O tempo para a temperatura fornece acesso a esses valores de dados para o sistema HVAC:
-
time_to_target- O tempo, em minutos, que levará para a estrutura atingir a temperatura desejada -
time_to_target_training- Status de treinamento
- Conforme o termostato aprende como o sistema HVAC responde, ele ajusta a estimativa para atingir a temperatura alvo
- Quando o termostato estiver razoavelmente certo da estimativa de tempo para atingir a temperatura desejada, o status mudará de
trainingparaready
Temperatura ambiente
A temperatura medida perto do termostato. Exibe o valor que corresponde à escala de temperatura preferida do usuário.
Escala de temperatura
As variáveis de temperatura ambiente e alvo são organizadas pela escala Celsius ou Fahrenheit. O atributo temperature_scale será "F" ou "C", dependendo da preferência do usuário. Esta propriedade é definida por cada termostato, portanto é possível que em uma única estrutura um usuário tenha dois termostatos, um em cada escala de temperatura. Mantenha as preferências do usuário em mente ao exibir os valores de temperatura.
Começando com as permissões da versão v5 , você pode alterar a escala de temperatura por meio da API.
Os campos de temperatura alvo e ambiente têm variantes _f e _c para acomodar arredondamentos consistentes ao exibir temperaturas.
Display de temperatura
Ao exibir as 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 trabalham juntos para determinar o que é mostrado no visor do Nest Thermostat e como ele se comporta.
- Quando
hvac_modeé definido comoheat-cool, o Nest Thermostat exibe os pontos de ajuste baixo e alto separados por um caractere marcador (•), caso contrário, o Nest Thermostat exibe apenas a temperatura desejada - Quando
hvac_modeestáoff, a palavra "OFF" é exibida no Nest Thermostat, no idioma de preferência do usuário - Quando
hvac_modeé definido comoeco, a palavra "ECO" é exibida no Nest Thermostat, no idioma preferido do usuário
O formato da temperatura de exibição também depende da escala de temperatura selecionada (F / C).
As temperaturas Fahrenheit são exibidas como números inteiros:
- Temperatura alvo: 55 ° F
- Temperatura ambiente: 62 ° F
As temperaturas 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 é exibido na frente do termostato, o termostato está configurado para uma temperatura de economia de energia e has_leaf = true .
Bloqueio de temperatura
Os usuários podem bloquear um Nest Thermostat para que ele só possa ser ajustado dentro de uma faixa de temperatura limitada. Começando com as permissões da versão v5 , você pode ver se o bloqueio de temperatura está ativado verificando is_locked e, se estiver, leia os valores mín / máx. De bloqueio de temperatura por meio da API:
As temperaturas de bloqueio devem ser especificadas em pares, como valores máximo e mínimo, e só podem ser gravadas se is_locked = true .
Umidade
Umidade, em formato de porcentagem (%), medida no dispositivo, arredondada para os 5% mais próximos.
Protetor solar
A tecnologia de protetor solar ajusta automaticamente a temperatura no Nest Thermostat para compensar os picos de calor que ocorrem devido à luz solar direta na unidade.
Esses valores de dados informarão se o protetor solar está ativado e / ou corrigindo ativamente a temperatura.
-
sunlight_correction_enabled- booleano, retorna
truese o protetor solar estiver habilitado
- booleano, retorna
-
sunlight_correction_active- booleano, retornatruese o protetor solar estiver ativo, indicando que o termostato está localizado na luz solar direta
Ventilador
Muitos sistemas HVAC têm ventiladores integrados, o que significa que o ventilador não pode ser controlado de forma independente . Não há modo desligado para ventiladores integrados, porque o ventilador precisa funcionar quando o aquecimento ou resfriamento está ligado.
No entanto, se o sistema HVAC for compatível, o ventilador pode ser explicitamente ligado via API, para deixar os ocupantes mais confortáveis, sem envolver todo o sistema HVAC.
Se o ventilador puder ser controlado de forma independente, has_fan será definido como true e os seguintes valores de dados podem ser definidos com permissões de leitura / gravação do termostato:
-
fan_timer_active- booleano, retornatruese o temporizador do ventilador estiver ativado por um período pré-programado -
fan_timer_duration- int, o período de tempo (em minutos) que o ventilador está configurado para funcionar
Use esses valores juntos para iniciar o cronômetro do ventilador (ligar o ventilador) por um período específico de tempo. Você também pode usar o valor fan_timer_timeout para determinar o registro de data e hora de quando o ventilador está configurado para parar de funcionar.
Observe que você sempre pode alterar fan_timer_duration - é independente de hvac_mode ou do estado de ocupação da estrutura (ausente).
Você pode esperar essas respostas em caso de sucesso ou falha:
- 200 OK
- 400 Bad Request
Se o comando para ligar o ventilador não produzir o resultado esperado, pode ser porque o ventilador já está acionado (manualmente pelo usuário, ou em uma programação, ou devido a um ciclo de aquecimento / resfriamento do HVAC).
Limitação de taxa
Aplicamos limitação de taxa para proteger contra chamadas excessivas para dispositivos, o que pode afetar o sistema ou o desempenho da bateria. Em condições normais, os dispositivos Nest carregam a bateria dos fios de baixa tensão no sistema de aquecimento e resfriamento. Mas se chamadas excessivas forem feitas em um curto período de tempo e o nível da bateria ficar baixo, o Nest Thermostat desligará 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 dentro de um período de tempo definido. Se você exceder esse limite, receberá uma resposta de erro e uma mensagem indicando que excedeu seu limite.
Para obter 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 pode atender à solicitação no momento. Se isso acontecer, aguarde algum tempo para que a bateria recarregue antes de tentar novamente.
Saiba mais sobre as condições de bateria fraca no Nest Learning Thermostat .
Mensagens de erro
Alguns estados tornam certas funções indisponíveis. Essas regras existem para economizar energia ou fornecer conforto e segurança.
Para obter informações sobre o que significam os erros de chamada de API e como lidar com eles, consulte Mensagens de erro .
Problema de conexão / Wi-Fi
Se um dispositivo estiver offline, as modificações não são permitidas. Você pode observar o estado online do dispositivo no modelo de dados e exibir a IU de forma adequada.