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 seu aquecimento e arrefecimento em qualquer lugar que tenha acesso a uma conexão de Internet.
Apoiando esses recursos requer um sofisticado sistema de controle que vai acima e além de programas baseados em valores nominais simples. 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 o poder necessário 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 estrutura e dispositivo "onde o nome" (localização na casa)
- etiqueta personalizada do termostato
- status online e informações de conexão passado
- as temperaturas actuais e alvo
- modo de temperatura
- Temperaturas eco
- Tempo-de-Temperatura
- escala de temperatura (conjunto F / C)
- Bloqueio de temperatura de estado, e se bloqueada, o mínimo de valores de temperatura / bloqueadas max
- duração do temporizador da ventoinha e modo HVAC
- Umidade
- Protetor solar
permissões 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 de HVAC
- temporizadores ventilador
Começando com termostato de leitura / gravação v5, você também pode atualizar o seguinte:
- escala de temperatura
- etiqueta termostato
identificadores termostato
Dispositivo
Nest dispositivos são listadas por tipo como uma matriz de identificações, que pode ser usada para identificar exclusivamente um dispositivo através 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 esse dispositivo. Para um dispositivo que instalou vários produtos do mesmo desenvolvedor, o desenvolvedor vai 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, rótulo aparece entre parênteses, após o nome onde.
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, salvo indicação em contrário.
| dados do Valor | Descrição |
|---|---|
locale | O código de idioma e país atribuído a esse dispositivo |
software_version | A cadeia que representa o firmware atualmente instalado no dispositivo |
structure_id | Uma cadeia que representa unicamente esta estrutura; esta é a estrutura que o dispositivo está emparelhado com |
last_connection | O timestamp da última conexão bem-sucedida ao 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. |
características 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. Termostatos neste ECO exibição do modo.
Estruturas têm dois estados relacionados com a presença: em casa ou fora. Quando nenhum movimento é detectado na casa, a estrutura vai mudar de casa para fora, e os termostatos em casa habilitará automaticamente Temperaturas Eco.
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 de HVAC | valores de dados de temperatura 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_f ou 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 |
Temperaturas eco
Temperaturas Eco permitir que o usuário para economizar energia, se eles estão em casa ou não. 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.
A comutação entre os modos de eco e não-eco
Seu produto não deve ser necessário para gerenciar as temperaturas alvo diretamente no modo Eco. Quando a casa está definido para longe, a temperatura alvo não é exibido, mas é definida internamente, com base na seleção do usuário. Quando o termostato está na posição OFF, então não há temperaturas alvo são observados.
Se você absolutamente deve mudar temperaturas alvo diretamente, certifique-se de fazer a mudança 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"
Depois destes passos, ajustar a temperatura alvo, 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 / vazia |
temperatura alvo
temperatura alvo é o valor mais importante para o sistema HVAC - é a temperatura desejada, normalmente definido pelo usuário. A maioria das ações e decisões são baseadas nele. A partir da API, trabalha com produtos Nest pode escrever a temperatura alvo, como parte de um processo maior.
Existe sempre um conjunto de temperatura alvo quando o sistema estiver 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
Há também temperaturas de segurança que são uma barreira para impedir o congelamento tubos ou temperaturas excessivamente altas em casa.
Quando o termostato estiver desligado, sem temperaturas alvo estão definidos.
Tempo-de-Temperatura
Time-to-Temperatura 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- estado de treinamento
- Como o termostato aprende as responde sistema de climatização, 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. Exibir o valor que corresponde à escala de temperatura preferida do utilizador.
escala de temperatura
As variáveis de temperatura ambiente e de destino são organizadas por escala Celsius ou Fahrenheit. O temperature_scale atributo será ou "F" ou "C", dependendo da preferência do utilizador. Essa propriedade é definida por cada termostato, por isso, é possível que em uma única estrutura de um usuário pode ter 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.
indicador 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 trabalhar juntos para determinar o que é mostrado no ninho exibição Termostato, 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 de exibição de temperatura, também depende da escala de temperatura seleccionada (F / C).
Fahrenheit temperaturas são exibidos como números inteiros:
- A temperatura alvo: 55 ° F
- Temperatura ambiente: 62 ° F
temperaturas Celsius são exibidos como um número inteiro ou um valor decimal, com o último conjunto de dígitos a" 0,5" :
- A 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 utilizadores podem bloquear um ninho termostato de modo que ela só pode ser ajustado dentro de uma gama limitada de temperaturas. 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
Humidade, no formato por cento (%), medida no dispositivo, arredondadas para o mais próximo de 5%.
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.
Estes valores de dados vai dizer se Protetor solar é habilitado e / ou corrigir 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á o modo para os fãs integrados, porque as necessidades de fãs a correr quando o aquecimento ou arrefecimento está ligado.
No entanto, se o sistema HVAC é compatível, o ventilador pode ser explicitamente ligado através da API, a fim de fazer ocupantes mais confortável, sem envolver o sistema HVAC completo.
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 temporizador do ventilador (o ventilador) por um período de tempo específico. 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 estas respostas em caso de sucesso ou fracasso:
- 200 OK
- 400 Bad Request
Se o comando para ligar o ventilador não produz o resultado esperado, pode ser porque o ventilador está ocupada (quer manualmente pelo utilizador, ou em uma programação, ou devido a um ciclo de calor HVAC / cool).
limitação de taxa
Nós aplicamos limitação de taxa para se proteger contra as chamadas excessivas para dispositivos, que podem afetar o sistema ou o desempenho da bateria. Sob condições normais, os dispositivos de ninho carregar a bateria a partir dos fios de baixa voltagem no sistema de aquecimento e de arrefecimento. Mas, se as chamadas excessivas são feitas em um curto período de tempo e o nível da bateria fica baixo, o Nest Thermostat vai desligar o Wi-Fi para poder conservar.
Na prática, isto significa que nós 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, você receberá uma resposta de erro e uma mensagem indicando que você excedeu o 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. Neste caso, você receberá uma resposta de erro e uma mensagem indicando que o dispositivo não pode atender à solicitação neste momento. Se isso acontecer, dar a bateria algum tempo para recarregar antes de tentar novamente.
Saiba mais sobre as condições de bateria fraca no Nest Learning Thermostat .
Mensagens de erro
Alguns estados tornar certas funções indisponíveis. Estas regras estão no local para conservar energia ou proporcionar 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 .
Wi-Fi emissão / conexão
Se um dispositivo estiver offline, as modificações não são permitidos. Você pode observar o estado on-line do dispositivo no modelo de dados e exibir UI apropriadamente.