Notice: We're retiring Works with Nest. See the home page for more information.
Google is committed to advancing racial equity for Black communities. See how.
Esta página foi traduzida pela API Cloud Translation.
Switch to English

Fora & amp; ETA

Longe

Na API do Nest, o conceito de "Casa" ou "Ausente" tem um efeito poderoso nos comportamentos dos recursos de economia e conveniência de energia do Nest.

Como o Home and Away funciona

O Nest usa uma variedade de sinais para detectar a presença humana em uma residência. Se o Nest não detectar presença por um longo período de tempo, ele definirá automaticamente a casa como Ausente. Quando detecta a presença humana, retorna a estrutura ao estado inicial.

A reação às alterações no status Casa / Ausência abre uma ampla gama de oportunidades para seus produtos. Por exemplo, seus produtos podem:

  • Apague as luzes quando a casa entrar Fora para economizar energia
  • Envie uma notificação se a porta da garagem estiver aberta quando a casa estiver ausente
  • Tocar música quando a casa muda para Home

Como o ETA funciona

Em alguns casos, os usuários têm um aplicativo de terceiros que usa GPS para fornecer dados de tempo estimado de chegada (ETA) à API do Nest. Em outros casos, o usuário pode usar um aplicativo para inserir manualmente seu ETA. Ou talvez o ETA seja calculado com base na programação regular do usuário.

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

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

Após a entrada do ETA no serviço Nest, outra integração do Works com Nest pode usá-lo como um sinal para preparar a casa para a chegada do usuário.

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

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

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

Dessa forma, não apenas a temperatura é confortável, as luzes também acendem quando o usuário chega em casa.

A reação às alterações no status da ETA abre uma ampla gama de oportunidades para seus produtos. Por exemplo, seus produtos podem:

  • Ligue a TV quando o usuário chegar em casa
  • Abra a porta da garagem quando o usuário estiver quase em casa
  • Já tem música tocando quando o usuário volta para casa

Permissões ausentes

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



Acesso

Leitura ausente
Leitura / gravação ausente

Leitura ETA

Leitura / gravação ETA

Leitura de alarme de fumaça + CO
Leitura do termostato
Leitura / gravação de termostato
away sim sim sim
eta_begin (somente leitura) sim sim
objeto eta (somente gravação) sim

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

Recursos ausentes

Casa e Fora

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

Valor Descrição
home Há alguém na estrutura. Este estado pode ser definido:
• pela Nest se tiver alta confiança dos dados do sensor de movimento
• pelo usuário através do aplicativo Nest, termostato Nest ou seu produto
• algoritmicamente via ETA
away Não há ninguém na estrutura. O usuário definiu explicitamente a estrutura como ausente, por meio do aplicativo Nest , do Nest Thermostat ou do seu produto.
unknown Se nenhum dispositivo estiver associado à estrutura, o estado ausente é unknown .

A API do Nest fornece a capacidade de definir diretamente Casa e Ausência, além de ouvir alterações nesses estados. No entanto, ao definir Casa e Fora, deve ser feito da mesma forma que o aplicativo Nest : como resultado de uma solicitação explícita do usuário. Tentar definir esse estado por algoritmos corre o risco de criar uma experiência confusa para o usuário e é proibido pelas políticas de design do Nest .

Esteja ciente de que os usuários sempre podem definir manualmente o estado Casa / Ausência.

Saiba mais sobre como os usuários definem os estados de origem e ausência .

ETA

Longe

ETA é um objeto com campos que podem ser definidos em uma estrutura. É usado para informar ao Nest que é esperado que um usuário volte para casa em um horário específico. Ao definir o ETA, 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áfego, planos de usuário alterados e outros eventos, os produtos devem atualizar o ETA periodicamente à medida que a viagem avança, fornecendo ao Nest um fluxo de horas de chegada estimadas (5 minutos é um intervalo ideal).

Quanto mais informações recebemos, mais confiantes podemos estar na confiabilidade das entradas do ETA, o que nos torna mais confiantes quando tomamos medidas para preparar a casa.

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

Faça uma chamada de gravação ETA

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

Valores de dados

Uma chamada ETA requer os seguintes valores de dados:

Nome Tipo Descrição
trip_id corda Identificador de viagem ETA exclusivo
estimated_arrival_window_begin corda Registro de data e hora
Deve ser maior que NOW , no formato ISO 8601
estimated_arrival_window_end corda Registro de data e hora
Deve ser maior que o estimated_arrival_window_begin , no formato ISO 8601

Devido à possibilidade de interrupções de conexão nas comunicações GPS, sugerimos um fluxo de amostras, idealmente uma vez a cada 5 minutos.

Toda chamada ETA deve incluir uma cadeia única trip_id que você define na chamada inicial. Outros parâmetros podem mudar com chamadas sucessivas para o mesmo trip_id .

Uma chamada ETA retorna um código de status HTTP 200 OK em caso de êxito.

Exemplos

Ondulação
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 ETA

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 sequência ("0"), ou a chamada falhará.

Mensagens de erro

Para obter informações sobre o significado dos erros de chamada da API e como lidar com eles, consulte Mensagens de erro .