Projetar uma automação no Android

Antes de começar a usar a API Automation, projete suas automações.

Determine os seguintes parâmetros para cada automação:

• As circunstâncias em que a automação deve ser sugerida ao usuário. Por exemplo, se o usuário acabou de adicionar três novas luzes à casa, ele pode se interessar por uma automação específica para controlar luzes.
• Quais tipos de dispositivo são necessários para a automação. Por exemplo, se o usuário acabou de adicionar três novas luzes à casa, ele pode se interessar por uma automação específica para controlar as luzes. Exemplos de tipos de dispositivos de iluminação incluem OnOffLightDevice, ColorTemperatureLightDevice, DimmableLightDevice ou ExtendedColorLightDevice.
• Quais atributos e comandos de trait são necessários para a automação e se eles são compatíveis com a API Automation no Android.
• Os atributos que devem ativar a automação como ativações. As ativações são discutidas em Componentes de automação no Android.
• Condições adicionais que determinam se a automação deve ser executada e quais ações devem ser realizadas.
• O fluxo de execução da automação. Ele deve ser executado de forma sequencial ou em paralelo? Você precisa de vários caminhos lógicos?

Ao projetar, pode ser útil diagramar o fluxo da automação, nó por nó, com a lógica necessária em cada etapa.

Depois de projetar uma automação, use a DSL de automação para criá-la. A automação que você cria é essencialmente um "modelo". Todas as estruturas e dispositivos nela são marcadores de posição e preenchidos com a estrutura e os dispositivos específicos de cada usuário quando eles "adotam" a automação para uso próprio.

Confira a seguir diferentes tipos de automações que um app pode criar usando as APIs Home. Consulte a página Criar uma automação para ver trechos de código relacionados a esses exemplos.

Automação simples

Digamos que você precise criar um app que gera uma automação para abrir as persianas às 8h. Para isso, o app precisa de uma lista das persianas (dispositivos com o tipo WindowCoveringDevice) presentes na estrutura que são compatíveis com automações, que podem ser fornecidas pela API Discovery.

Para automações que precisam ser executadas em um determinado horário, você também precisa garantir que o usuário tenha atribuído um endereço à estrutura escolhida (durante a criação da estrutura ou no Google Home app (GHA)). Caso contrário, a automação não saberá o fuso horário em que será executada. A API Discovery pode ajudar a determinar se um endereço foi atribuído à estrutura.

O fluxo de execução seria mais ou menos assim:

1. Usando a API Discovery, colete a lista de dispositivos WindowCoveringDevice.
2. Se o endereço não estiver preenchido, notifique o usuário de que ele precisa fornecer um endereço (por exemplo, no GHA) e interrompa a execução.
3. Caso contrário, defina a automação:
   1. Inicie a automação às 8h.
   2. Para cada uma das persianas, chame o comando upOrOpen do atributo WindowCovering.

Automação complexa

Imagine um app que cria uma automação que aciona luzes piscantes quando um movimento é detectado.

Uma das primeiras tarefas na implementação desse app é descobrir quais luzes estão disponíveis na casa do usuário usando a API Discovery. Com essas informações, o app pode mostrar as luzes disponíveis e permitir que o usuário selecione as que quer que pisquem.

O fluxo de execução:

1. Usando a API Discovery, colete a lista de dispositivos de iluminação presentes na estrutura, que seriam todos os dispositivos com um tipo de dispositivo OnOffLightDevice, ColorTemperatureLightDevice, DimmableLightDevice ou ExtendedColorLightDevice.
2. Ofereça uma maneira de selecionar as luzes que piscam, talvez por um painel de configurações personalizado.
3. Defina a automação:
   1. Inicie a automação sempre que alguém sair ou chegar ao local, monitorando AreaPresenceState.
   2. Se o presenceState indicar que a estrutura está ocupada, pisque as luzes escolhidas.

Automação genérica

Para um exemplo de automação mais sofisticada, considere uma que orienta o usuário na criação de uma automação aberta, com base em qualquer um ou em todos os dispositivos que ele tem em casa.

A automação pode pedir que o usuário selecione uma estrutura primeiro.

Em seguida, a automação pode exibir todos os ambientes da estrutura em uma visualização resumida expansível, em que a expansão de um ambiente mostra os dispositivos nele. Ao expandir ainda mais um dispositivo, as ativações e os comandos compatíveis com ele são listados.

O usuário pode escolher os dispositivos, as ativações e os comandos que quer usar, e a automação orienta o usuário na montagem de uma automação.

Quando todas as escolhas e decisões do usuário forem finais, a automação será gerada e salva na estrutura escolhida.

Em um nível geral, essa automação precisaria coletar vários conjuntos de dados sobre a casa do usuário usando a API Structure para Android, a API Device para Android e a API Discovery.

Tabela 1: APIs Home e as informações que elas podem fornecer

API	Informações
API Structure	Quais estruturas estão disponíveis? Quais ambientes estão na estrutura
API Device	Quais dispositivos estão na estrutura escolhida Onde esses dispositivos estão localizados (em qual ambiente)
API Discovery	Quais atributos são compatíveis com os dispositivos Quais ativações e comandos estão disponíveis nesses atributos Quais restrições existem nos parâmetros desses comandos