Termostato

Controle do termostato

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)".

Nome Nome longo

name_long

Neste exemplo, name_long é "Escritório (no andar superior)".

Nome longo em uma mensagem

Identificador

Nome (rótulo)
Nome (rótulo)

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 onde name

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_f
ou
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:

  1. Mude o hvac_mode para qualquer outro valor, exceto eco.
  2. Modificar os valores de dados target_temperature apropriados

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:

  1. conseguir previous_hvac_mode
  2. Defina hvac_mode como o valor previous_hvac_mode.
  3. confirme se hvac_mode nã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 única target_temperature é definida.
  • Quando a opção Aquecer • Resfriar (heat-cool) está selecionada, dois valores target_temperature sã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 desejada
  • time_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 training para ready

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

Termostato

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_mode está definido como heat-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 como off, a palavra "Off" é exibida no térmico do Nest, no idioma de preferência do usuário.
  • Quando hvac_mode é definido como eco, 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.

Folha

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.

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, retorna true se o timer do ventilador estiver envolvido por uma duração pré-programada
  • fan_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.