O Nest Learning Thermostat ™ é um dispositivo conectado à Internet que é intuitivo e fácil de usar, continuamente aprendendo sobre os padrões de uso em casa para o conforto otimizar e poupar 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. Nest oferece uma ampla gama de algoritmos (como no início , verdadeira Radiant , Airwave ™ ) que exigem uma quantidade significativa de poder 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 é projetado para permitir que os produtos para controlar o sistema HVAC sem interromper algoritmos ninho 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)
- Rótulo de termostato personalizado
- 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)
- Bloqueio de temperatura de estado, e se bloqueada, o mínimo de valores de temperatura / bloqueadas max
- 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 API termostato, selecione o Termostato ler permissão para o seu cliente.
Para acesso de leitura a todos os valores de dados API termostato e acesso de gravação adicional para selecionar valores, selecione o termostato leitura / gravação permissão para o seu cliente. Este nível de permissão permite que você atualize o seguinte:
- Temperatura alvo
- Modo HVAC
- Cronômetros de ventilador
A partir do termostato de leitura / gravação v5, você também pode atualizar o seguinte:
- Escala de temperatura
- Etiqueta 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. Assim, um ID termostato de "peyiJNo..." significa que você pode carregar o modelo do dispositivo termostato em devices/thermostats/peyiJNo... através 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. Quanto mais curto name atributo é exibido em etiquetas de interface do usuário, enquanto name_long é utilizado em longo texto formulário.
name
Nestes exemplos, name é "corredor" ou "corredor (West)".
name_long
Neste exemplo, name_long é "escritório (Upstairs)".
Rótulo
Começando com versão permissões v5 , você pode adicionar um costume termostato rótulo através da API. No app Nest, o rótulo aparece entre parênteses, após o nome where.
Começando com versão permissões v6 , você também pode ler o rótulo do termostato.
Onde
where_id
- Um identificador exclusivo, gerado-Nest que representa
name -
where_idé só de leitura, e é criado automaticamente na chamada para criar um personalizado, ondename
Saiba mais sobre onde nomes para termostatos Ninho , Ninho Protege e ninho de webcams .
where_name
Quando você escolher qualquer uma das permissões termostato , você pode acessar o dispositivo where_name do objeto de dispositivo ( devices/thermostats ).
Outros metadados
Todos os valores de dados são somente leitura, a menos que 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 essa 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. Isto é determinado pelo ninho usando o last_connection tempo e de uma janela de religação esperado que é específico do dispositivo. |
Recursos do termostato
Modos de termostato
Sistemas HVAC tem quatro "em" estados ( heat , cool , heat-cool , eco ) e um estado "desligado" ( off ). Usamos esses estados para gerenciar conforto e poupança energética através hvac_mode valores de dados e de temperatura.
- Quando o calor ou o modo de fresco (
heat,cool) é seleccionado, o termostato ajusta a casa com a temperatura alvo. - Quando o calor • modo Cool (
heat-cool) é selecionado, o termostato irá manter a casa confortável, dentro de uma gama de temperatura preferida. - Quando Temperaturas Eco (ECO) é selecionado, o termostato irá aplicar algoritmos de poupança 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 hvac_mode valores de temperatura e trabalhar juntos
Dependendo do valor de hvac_mode , apenas determinados valores de dados de temperatura pode ser acedida 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 em torno mudando hvac_mode :
| Cenário | Pode hvac_mode ser mudado? |
|---|---|
| Bloqueio temperatura está habilitado | sim |
| Emergency Shutoff está ativo | Não |
| Emergência de calor está habilitado | Não |
can_cool ou can_heat valor é false | Não |
Eco temperaturas
As temperaturas ecológicas permitem que o usuário economize energia, esteja ou não em casa. Considere mudar o hvac_mode de eco ao implementar comportamentos de poupança de energia em seu produto.
Eco endpoints Temperatura estão disponíveis na API Nest começando com termostato ler e permissões de leitura / v6 gravação.
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:
- Mudança
hvac_modepara qualquer outro valor excetoeco - Modificar as apropriado
target_temperaturevalores de dados
Começando com termostato ler e ler / escrever permissões v6, você pode acessar previous_hvac_mode através da API para ajudar com transições de modo HVAC. previous_hvac_mode é usado para armazenar o hvac_mode do dispositivo antes que a transição para o "eco".
Por exemplo, se o Nest Thermostat está usando Eco Temperaturas ( hvac_mode = "eco" ), previous_hvac_mode está disponível, e você quer que seu produto conjunto target_temperature , então você deve primeiro:
- get
previous_hvac_mode - conjunto
hvac_modeaoprevious_hvac_modevalor - confirm
hvac_modenão é mais definida como "eco"
Após essas etapas, defina as temperaturas desejadas conforme apropriado.
Dependendo do hvac_mode valor, isto é como previous_hvac_mode muda:
Quando hvac_mode estado é ... | 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 - é 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 de fresco (calor ou
heat,cool) é seleccionado, uma únicatarget_temperatureé conjunto - Quando o calor • modo de fresco (
heat-cool) é seleccionado, doistarget_temperaturevalores são definidos, denotando um intervalo alvo, um maior para um arrefecimento e uma inferior para o aquecimento - Quando o modo de Eco (
eco) é seleccionado, o intervalo 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
Time-to-Temperature dá-lhe acesso a estes valores de dados para o sistema HVAC:
-
time_to_target- O tempo, em minutos, que levará para que a estrutura para atingir a temperatura alvo -
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 é razoavelmente certo da estimativa de tempo para atingir a temperatura alvo, 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 temperature_scale atributo será ou "F" ou "C", dependendo da preferência do utilizador. 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 valores de temperatura.
Começando com versão permissões v5 , é possível alterar a escala de temperatura através da API.
Alvo e ambientais campos de temperatura têm _f e _c variantes para acomodar arredondamento consistente quando visualizadas temperaturas.
Display de temperatura
Quando você exibir informações de temperatura alvo, considere estes três valores dependentes: temperature_scale , hvac_mode , e da estrutura away estado.
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 ninho termostato exibe a baixas e altas setpoints separados por um caractere de marcador (•), caso contrário, os monitores ninho termostato a temperatura alvo - Quando
hvac_modeestá definido paraoff, a palavra "OFF" é exibido no Ninho termostato, no idioma de preferência do usuário - Quando
hvac_modeestá definido paraeco, a palavra "ECO" é exibido no Ninho termostato, no idioma de preferência 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 da folha está mostrando na parte frontal do termostato, o termostato está definido para uma temperatura de poupança 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 versão permissões v5 , você pode ver se Temperatura Bloqueio está ativada, verificando is_locked , e se for, ler valores min / max bloqueio de temperatura através da API:
Temperaturas de bloqueio deve ser especificado em pares, como valores máximos e mínimos, e só pode ser escrito se is_locked = true .
Umidade
Umidade, em formato de porcentagem (%), medida no dispositivo, arredondada para os 5% mais próximos.
Protetor solar
Protetor solar tecnologia ajusta automaticamente a temperatura no ninho termostato para compensar picos de calor que ocorrem luz directa do sol a partir do aparelho.
Esses valores de dados informarão se o protetor solar está habilitado e / ou corrigindo ativamente a temperatura.
-
sunlight_correction_enabled- boolean, retorna
truese Protetor solar é habilitado
- boolean, retorna
-
sunlight_correction_active- boolean, retornatruese Protetor solar é ativo, indicando que o termostato está localizado na luz solar direta
Ventilador
Muitos sistemas de climatização têm fãs integrado, 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 estiver 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 pode ser controlada independentemente, has_fan será definido como true , e os seguintes valores de dados pode ser definido com termostato permissões de leitura / gravação:
-
fan_timer_active- boolean, retornatruese o temporizador do ventilador é contratado por um período pré-programado -
fan_timer_duration- int, o período de tempo (em minutos) que o ventilador está definido para ser executado
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 fan_timer_timeout valor para determinar o timestamp de quando o ventilador está definido para parar de correr.
Note-se que você sempre pode mudar fan_timer_duration - é independente da hvac_mode ou estado estrutura ocupação (de distância).
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 desempenho do sistema ou da bateria. Em condições normais, os dispositivos Nest carregam a bateria com os 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 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 recarregar a bateria 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 os erros de chamadas API significa e como lidar com eles, ver 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.