O Nest Learning ThermostatTM é um dispositivo conectado à Internet, intuitivo e fácil de usar. Ele aprende continuamente sobre padrões de uso doméstico para otimizar o conforto e economizar energia. Os usuários podem controlar o aquecimento e resfriamento em qualquer lugar onde tenham acesso a uma conexão de Internet.
Para oferecer suporte a esses recursos, é necessário ter um sistema de controle sofisticado que vá fora dos programas simples baseados em temperaturas definidas. O Nest oferece uma ampla variedade de algoritmos (como Early On, True Radiant, AirwaveTM) que exigem uma quantidade significativa de capacidade computacional em comparação com a maioria dos termostatos. O Nest Thermostat está habilitado para fornecer esses recursos avançados.
A API Nest foi projetada para permitir que os produtos controlem o sistema HVAC (Aquecimento, ventilação e ar-condicionado) sem interromper os algoritmos do Nest ou surpreender o usuário com comportamentos inesperados. Eles fornecem acesso aos seguintes dados do Nest Thermostat:
- Estrutura do nome e do dispositivo: nome da empresa (local na casa)
- Rótulo personalizado do termostato
- Status on-line e informações sobre a última conexão
- Temperaturas atuais e desejadas
- Modo de temperatura
- Temperaturas ecológicas
- Tempo até a temperatura
- Escala de temperatura (definição de F/C)
- Status do 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 acesso de leitura a todos os valores de dados da API Thermostat, selecione a permissão Termostato de leitura para seu cliente.
Para acesso de leitura a todos os valores de dados da API Thermostat e acesso adicional de gravação aos valores selecionados, selecione a permissão Termos/leituras/gravação 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, 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 matriz de IDs, que podem ser usados para
identificar exclusivamente um dispositivo por meio do caminho dele. Portanto, um ID de termostato de
"peyiJNo..." significa que você pode carregar o modelo de dispositivo de termostato em
devices/thermostats/peyiJNo... pela API.
Quando um dispositivo está conectado a vários produtos, cada desenvolvedor vê um código diferente para o dispositivo. Para um dispositivo que tenha instalado vários produtos do mesmo desenvolvedor, ele verá o mesmo ID.
Nome
Dois atributos de nome são fornecidos. O atributo name mais curto é exibido nos
rótulos da interface do usuário, enquanto name_long é usado em textos de formato longo.
name
Nesses exemplos, name é "Hallway" ou "Hallway (Oeste)".
name_long
Neste exemplo, name_long é "Escritório (no andar superior)".
Identificador
A partir da versão de permissões v5, é possível adicionar um rótulo de termostato personalizado usando a API. No app Nest, a etiqueta 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.
Em que
where_id
- Um identificador exclusivo gerado pelo Nest que representa
name. where_idé somente leitura e criado automaticamente na chamada para criar um personalizado ondename
Saiba mais sobre os nomes dos Nest Thermostats, Nest Protects e Nest Cams.
where_name
Quando você escolhe uma das permissões
Thermostat, pode
acessar o dispositivo where_name do objeto do dispositivo (devices/thermostats).
Outros metadados
Todos os valores de dados são somente leitura, salvo especificação em contrário.
| Valor dos dados | Descrição |
|---|---|
locale |
O código de idioma e de país atribuídos a este dispositivo |
software_version
|
Uma string que representa o firmware instalado no dispositivo |
structure_id
|
Uma string que representa exclusivamente essa 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 Nest |
is_online
|
Status on-line. Isso é determinado pelo Nest usando o
tempo last_connection e uma janela de reconexão
específica do dispositivo. |
Recursos do termostato
Modos do termostato
Os sistemas HVAC (aquecimento, ventilação e ar-condicionado) têm quatro estados "quot;on" (heat, cool, heat-cool, eco) e um estado "quot
off" (off). Usamos esses estados para gerenciar a economia de conforto e energia
por meio dos valores de dados de temperatura hvac_mode e hvac_mode.
- Quando o modo de aquecimento ou refrigeração (
heat,cool) está selecionado, o termostato ajusta a casa à temperatura-alvo. - Quando a opção Aquecer • Resfriar (
heat-cool) está selecionada, o termostato mantém a casa confortável dentro de uma faixa de temperatura preferencial. - Quando a opção Temperaturas econômicas (eco) estiver selecionada, o termostato aplicará 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" e "Ausente". Quando nenhum movimento é detectado na casa, a estrutura muda de "Em casa" para "Ausente", e as Termostatos da casa ativam as Temperaturas econômicas automaticamente.
Como hvac_mode e os valores de temperatura funcionam juntos
Dependendo do valor de hvac_mode, apenas 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 podem ser acessados |
|---|---|
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 algumas situações, há regras especiais sobre a alteração de hvac_mode:
| Cenário | hvac_mode pode ser alterado? |
|---|---|
| O bloqueio de temperatura está ativado | Sim |
| A desligamento de emergência está ativa | No |
| O aquecimento de emergência está ativado | No |
O valor de can_cool ou can_heat é false |
No |
Temperaturas econômicas
Com as Temperaturas econômicas, o usuário economiza energia, estando 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 ecológica estão disponíveis na API Nest a partir das permissões de leitura e leitura/gravação do termostato v6.
Como alternar entre os modos ecológico e não ecológico
O produto não precisa gerenciar as temperaturas-alvo 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 está desativado, não há temperaturas desejadas.
Se você precisar mudar as temperaturas-alvo diretamente, faça a mudança em duas chamadas separadas:
- Mude o
hvac_modepara qualquer outro valor, excetoeco. - Modificar os valores de dados
target_temperatureapropriados
A partir das permissões de leitura e leitura/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 de
fazer a transição para "eco"
Por exemplo, se o Nest Thermostat estiver usando as Temperaturas econômicas (hvac_mode =
"eco"), previous_hvac_mode estará disponível e você quiser que seu produto defina
target_temperature. Nesse caso, primeiro é necessário:
- conseguir
previous_hvac_mode - Defina
hvac_modecomo 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 da hvac_mode, veja como 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, 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 são baseadas nele. Com a API, os produtos Works with Nest podem gravar a temperatura-alvo como parte de um processo maior.
Sempre há uma temperatura-alvo definida quando o sistema está ativado.
- Quando o modo de aquecimento ou refrigeração (
heat,cool) é selecionado, uma únicatarget_temperatureé definida. - Quando a opção Aquecer • Resfriar (
heat-cool) está selecionada, dois valorestarget_temperaturesão definidos, indicando um intervalo de segmentação, um mais alto para resfriamento e um mais baixo para aquecimento. - Quando o modo Eco (
eco) é selecionado, a faixa de temperatura-alvo é definida internamente
Também há temperaturas de segurança que evitam o congelamento de encanamentos ou temperaturas excessivamente altas em casa.
Quando o termostato está DESATIVADO, nenhuma temperatura desejada é definida.
Tempo até a temperatura
O tempo de temperatura fornece acesso a estes valores de dados para o sistema HVAC:
time_to_target: o tempo, em minutos, que a estrutura levará para atingir 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 atingir a temperatura-alvo
- Quando o termostato tiver a estimativa de tempo para atingir 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 Celsius ou de 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 tenha 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 usando a API.
Os campos de temperatura ambiente e de destino têm variantes _f e _c para acomodar
um arredondamento consistente ao exibir temperaturas.
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 é exibido na tela do Nest Thermostat e como ele se comporta.
- Quando
hvac_modeestá definido comoheat-cool, o Nest Thermostat mostra os pontos de temperatura baixos e altos separados por um caractere de marcador (•). Caso contrário, o Nest Thermostat exibe apenas a temperatura desejada. - Quando
hvac_modeé definido comooff, a palavra "Off" é exibida no térmico do Nest, no idioma de preferência do usuário. - Quando
hvac_modeé definido comoeco, a palavra "ECO" é exibida no térmico do Nest, 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 em Fahrenheit são exibidas como números inteiros:
- Temperatura-alvo: 10 °C
- Temperatura ambiente: 16 °C
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 é exibido na frente do termostato, ele é
definido como uma temperatura que economiza energia, e has_leaf = true.
Bloqueio de temperatura
Os usuários podem bloquear o Nest Thermostat para que ele só possa ser ajustado em uma
faixa de temperatura limitada. A partir da versão
de permissão v5, é possível ver
se o bloqueio de
temperatura está ativado
verificando
is_locked. Caso esteja,
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áximo e mínimo, e
só podem ser gravadas se is_locked = true.
Umidade
Umidade, em formato percentual (%), medida no dispositivo, arredondada para o 5% mais próximo.
Filtro solar
A tecnologia Filtro solar ajusta automaticamente a temperatura do Nest Thermostat para compensar os picos de calor que ocorrem devido à luz solar direta na unidade.
Esses valores de dados informam se o Filtro solar está ativado e/ou corrigindo ativamente a temperatura.
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 na luz solar direta.
Ventilador
Muitos sistemas de HVAC (aquecimento, ventilação e ar-condicionado) têm ventiladores integrados, o que significa que eles não podem ser controlados de forma independente. Não há modo de desativação para ventiladores integrados, porque ele precisa funcionar quando o aquecimento ou resfriamento está ligado.
No entanto, se o sistema HVAC (aquecimento, ventilação e ar-condicionado) for compatível, ele poderá ser ligado explicitamente pela API para que os ocupantes fiquem mais confortáveis, sem usar todo o sistema HVAC (aquecimento, ventilação e ar-condicionado).
Se o ventilador puder ser controlado de maneira independente, has_fan será definido como true, e os valores de dados a seguir poderão ser configurados com permissões de leitura/gravação do termostato:
fan_timer_active: booleano, retornatruese o timer do ventilador estiver envolvido por uma duração pré-programadafan_timer_duration: a duração, em minutos, em que o ventilador está configurado para execução.
Use esses valores juntos para iniciar o timer do ventilador (ligar 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.
Você pode mudar fan_timer_duration: isso independe do hvac_mode ou do estado de ocupação da estrutura (fora dele).
Você pode esperar estas respostas em caso de sucesso ou falha:
- 200 OK
- 400 Solicitação inválida
Se o comando para ligar o ventilador não produzir o resultado esperado, pode ser porque o ventilador já está envolvido (manualmente pelo usuário, em uma programação ou devido a um ciclo de aquecimento/refrigeração HVAC).
Limitação de taxa
Aplicamos uma 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 dos fios de baixa tensão do sistema de aquecimento e resfriamento. No entanto, se forem feitas chamadas em excesso em um curto período e o nível da bateria estiver baixo, o Nest Thermostat 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 você exceder esse limite, receberá uma resposta de erro e uma mensagem indicando que você 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 consegue atender à solicitação no momento. Se isso acontecer, espere um pouco para a bateria recarregar antes de tentar novamente.
Saiba mais sobre condições de bateria fraca no Termostato Nest Learning.
Mensagens de erro
Alguns estados tornam determinadas funções indisponíveis. Essas regras existem 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 Wi-Fi / conexão
Se um dispositivo estiver off-line, as modificações não serão permitidas. Você pode observar o estado on-line do dispositivo no modelo de dados e exibir a IU corretamente.