Notice: We're retiring Works with Nest. See the home page for more information.
O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.
Esta página foi traduzida pela API Cloud Translation.
Switch to English

Ausente e HEC

Longe

Na API Nest, o conceito de "Casa" ou "Fora" tem um efeito poderoso sobre os comportamentos de economia de energia e recursos de conveniência da Nest.

Como funcionam em casa e fora

O Nest usa uma variedade de sinais para detectar a presença humana em uma casa. 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, ele retorna a estrutura ao estado inicial.

Reagir às mudanças no status Casa / Fora abre uma ampla gama de oportunidades para seus produtos. Por exemplo, seus produtos podem:

  • Apague as luzes quando a casa se afasta para conservar energia
  • Envie uma notificação se a porta da garagem estiver aberta quando a casa estiver ausente
  • Toque música quando a casa mudar para casa

Como funciona o ETA

Em alguns casos, os usuários têm um aplicativo de terceiros que usa GPS para fornecer dados de tempo estimado de chegada (ETA) para a API 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 apps 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 de ETA / termostato existe na conta do usuário, os dados de ETA ficam disponíveis para outros desenvolvedores do Works with Nest usarem em suas integrações do Works with Nest.

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

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

O ponto importante a ter em mente é que os dados do ETA devem ser inseridos por terceiros. A Nest não fornece dados de ETA atualmente. Se os dados ETA não foram gravados, a API Nest retorna o valor padrão "1970-01-01T00: 00: 00.000Z".

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

Dessa forma, além da temperatura confortável, as luzes também ficam acesas quando o usuário chega em casa.

Reagir às mudanças no status do ETA abre uma ampla gama de oportunidades para seus produtos. Por exemplo, seus produtos podem:

  • Ligue a TV quando o usuário se aproximar de casa
  • Abra a porta da garagem quando o usuário estiver quase em casa
  • A música já está tocando quando o usuário voltar para casa

Permissões de ausência

Os seguintes níveis de permissão de acesso estão disponíveis para valores de dados relacionados à ausência :



Acesso

Ausente lido
Leitura / gravação ausente

ETA lido

Leitura / gravação ETA

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

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

Recursos ausentes

Casa e Fora

O valor dos dados away pode dizer se o Nest pensa 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 confiabilidade dos dados do sensor de movimento
• pelo usuário por meio do app Nest , do Nest Thermostat ou do seu produto
• algoritmicamente via ETA
away Não há ninguém na estrutura. O usuário definiu explicitamente a estrutura como ausente, seja por meio do app Nest , do Nest Thermostat ou do seu produto.
unknown Se nenhum dispositivo estiver associado à estrutura, o estado ausente será unknown .

A API Nest fornece a capacidade de definir diretamente Casa e Ausente, bem como ouvir as alterações nesses estados. No entanto, ao definir Casa e Ausente, isso deve ser feito como o app Nest : como resultado de uma solicitação explícita do usuário. Tentar definir este estado algoritmicamente corre o risco de criar uma experiência do usuário confusa e é proibido pelas políticas de design do Nest .

Esteja ciente de que os usuários sempre têm a capacidade de definir manualmente o estado Casa / Ausente.

Saiba mais sobre como os usuários definem os estados Casa e Ausente .

ETA

Longe

ETA é um objeto com campos que podem ser definidos em uma estrutura. É usado para informar a Nest que o usuário deve voltar 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 em torno das viagens podem mudar devido ao tráfego, alterações nos planos do usuário e outros eventos, os produtos devem atualizar o ETA periodicamente à medida que a viagem avança, fornecendo à Nest um fluxo de tempos de chegada estimados (5 minutos é o intervalo ideal).

Quanto mais informações recebemos, mais confiantes podemos estar na confiabilidade dos insumos do ETA, o que nos deixa mais confiantes na hora de preparar a casa.

ETA é independente do estado de origem. Se o horário de chegada de um ETA conflitar com outro ETA, o horário de chegada mais próximo terá precedência.

Faça uma chamada de escrita do ETA

A lógica ETA depende da presença de um termostato na estrutura. Se não houver termostato na estrutura, as chamadas feitas ao objeto ETA falham com a mensagem de erro "Nenhum dispositivo emparelhado" . Este erro ocorre mesmo se outros tipos de dispositivos existirem na estrutura (por exemplo, uma 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 Timestamp
Deve ser maior que NOW , no formato ISO 8601
estimated_arrival_window_end corda Timestamp
Deve ser maior que estimated_arrival_window_begin , no formato ISO 8601

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

Cada chamada ETA deve incluir uma string trip_id exclusiva 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 sucesso.

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 um 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 obter informações sobre o que significam os erros de chamada de API e como lidar com eles, consulte Mensagens de erro .