Ausente &HEC

Na API Nest, o conceito de "Em casa" ou "Ausente" tem um efeito poderoso sobre os comportamentos dos recursos de economia e conveniência da Nest.

Como funcionam os modos "Em casa" e "Ausente"

O Nest usa vários sinais para detectar a presença humana em uma casa. Se o Nest não detectar presença por um longo período, ele definirá a casa automaticamente como "Ausente". Ao detectar a presença humana, ele retorna a estrutura para o estado inicial.

Reagir a mudanças no status "Em casa/Ausente" abre uma ampla variedade de oportunidades para seus produtos. Por exemplo, seus produtos podem:

• Apague as luzes quando a casa entrar no modo "Ausente" para economizar energia
• Enviar uma notificação se a porta da garagem estiver aberta quando a casa estiver ausente
• Tocar música quando a casa mudar para o modo "Em casa"

Como o HEC funciona

Em alguns casos, os usuários têm um app de terceiros que usa GPS para fornecer dados estimados de horário de chegada (ETA) à API Nest. Em outros casos, o usuário poderá usar um app para inserir o HEC manualmente. Ou o HEC pode ser calculado com base na programação regular do usuário.

Os apps ETA integrados ao Nest Thermostat faz com que o termostato comece a aquecer ou resfriar a casa antes que o usuário chegue.

Quando a integração de ETA/termostato existe na conta do usuário, os dados de ETA ficam disponíveis para que outros desenvolvedores do Works with Nest usem nas integrações do Works with Nest.

Depois que o HEC for inserido no serviço Nest, outra integração do Works with Nest poderá usá-lo como um sinal para preparar a casa para a chegada do usuário.

1. O HEC é escrito por um desenvolvedor Nest usando a chamada de API PUT eta somente para gravação.
2. O Nest Thermostat usa esses dados.
3. Se outros desenvolvedores também quiserem usá-lo, eles poderão usar a chamada de API GET eta_begin somente leitura.

O ponto importante a ser lembrado é que os dados de HEC precisam ser inseridos por terceiros. Atualmente, a Nest não fornece dados de HEC. Se os dados do HEC não tiverem sido gravados, a API Nest retornará o valor padrão "quot;1970-01-01T00:00:00.000Z".

Imagine, por exemplo, que você é um fornecedor de iluminação. Você pode receber os dados de ETA fornecidos pela integração de ETA/termostato e usá-los como um sinal para acender as luzes.

Dessa forma, além de a temperatura ficar confortável, as luzes também estarão acesas quando o usuário chegar em casa.

Reagir a mudanças no status de HEC abre uma ampla variedade de oportunidades para os produtos. Por exemplo, seus produtos podem:

• Ligar a TV quando o usuário se aproximar de casa
• Abrir a porta da garagem quando o usuário estiver quase em casa
• Têm músicas tocando quando o usuário volta para casa

Permissões "Ausente"

Os seguintes níveis de permissão de acesso estão disponíveis para valores de dados relacionados "fora":

Para mais informações, consulte a Visão geral de permissões.

Recursos "Ausente"

Modos "Em casa" e "Ausente"

O valor dos dados away pode informar se o Nest acredita que a estrutura está ocupada. Os valores possíveis são:

A API Nest permite definir diretamente o modo "Em casa" e "Ausente", bem como detectar alterações nesses estados. No entanto, ao configurar os modos"Em casa"e"Ausente", isso precisa ser feito como o app Nest, como resultado de uma solicitação explícita do usuário. Tentar definir esse estado por algoritmo corre o risco de criar uma experiência confusa para o usuário e é proibido pelas políticas de design do Nest.

Saiba que os usuários sempre podem definir manualmente o estado "Em casa" e "Ausente".

Saiba mais sobre como os usuários definem os estados "Em casa" e "Ausente".

HEC

O ETA é um objeto com campos que podem ser definidos em uma estrutura. É usado para informar ao Nest que um usuário espera que volte para casa em um horário específico. Ao configurar o HEC, um produto gera um trip_id exclusivo e fornece uma janela de chegada esperada, especificada pelos seguintes valores:

• estimated_arrival_window_begin
• estimated_arrival_window_end

Como as circunstâncias das viagens podem mudar devido ao trânsito, planos de usuário alterados e outros eventos, os produtos precisam atualizar o HEC periodicamente conforme a viagem avança, proporcionando ao Nest um fluxo de horários de chegada estimados (cinco minutos é um intervalo ideal).

Quanto mais informações recebermos, mais confiança teremos nas confiabilidades das entradas de HEC, o que nos faz mais confiantes ao tomar medidas para preparar a casa.

O HEC é independente do estado de origem. Se o horário de chegada de um HEC entrar em conflito com outro, o horário de chegada mais próximo terá precedência.

Fazer uma chamada de gravação no ETA

A lógica do ETA depende da presença de um Termostato na estrutura. Se não houver um termostato na estrutura, as chamadas feitas para o objeto de HEC falharão com a mensagem de erro "Nenhum dispositivo pareado". Esse erro ocorre mesmo que haja outros tipos de dispositivos na estrutura (por exemplo, uma Nest Cam ou um Nest Protect).

Valores de dados

Uma chamada de ETA requer os seguintes valores de dados:

Devido à possibilidade de falhas na conexão nas comunicações por GPS, sugerimos um fluxo de amostras, de preferência uma vez a cada cinco minutos.

Cada chamada de ETA precisa incluir uma string trip_id exclusiva, definida na chamada inicial. Outros parâmetros podem mudar com chamadas sucessivas para o mesmo trip_id.

Uma chamada de HEC retorna um código de status HTTP 200 OK quando a operação é concluída.

Examples

curl --location-trusted -X PUT -d \
  '{"trip_id":"sample-trip-id","estimated_arrival_window_begin":"2014-10-31T22:42:00.000Z","estimated_arrival_window_end":"2014-10-31T23:59:59.000Z"}' \
  "http://developer-api.nest.com/structures/5af48890-b516-11e3-9eff-123139166438/eta.json?auth=c.VG6bfzyOxAltaih6P4v..."

Cancelar uma HEC

Para cancelar um eta, envie estimated_arrival_window_begin = 0. Verifique se você está enviando um número inteiro (0) nesta chamada, não uma string ("0"), ou a chamada falhará.

Mensagens de erro

Para mais informações sobre o que significam erros de chamada de API e como lidar com eles, consulte Mensagens de erro.