Automações
Gatilho por Template
Quando um evento simples não representa a situação necessária, o gatilho por template combina estados, atributos, funções e cálculos em uma expressão booleana. Em Home Assistant, templates Jinja podem reagir quando a expressão passa de false para true e são reavaliados conforme entidades referenciadas mudam. O mecanismo integra dados heterogêneos sem criar dispositivo novo, mas depende de dependências detectáveis, tipos corretos e tratamento de unavailable; templates excessivamente complexos dificultam rastreio e podem consumir processamento.
⚙ Definição Técnica
Gatilho por template é um mecanismo de avaliação reativa no qual uma expressão computa um resultado lógico a partir de estados, atributos, variáveis, tempo ou funções e inicia a automação quando esse resultado assume a condição de disparo definida. Em motores como o Home Assistant, a expressão normalmente é reavaliada quando entidades referenciadas mudam, e a transição de falso para verdadeiro gera o evento; a semântica exata de inicialização, duração e dependências varia por plataforma. O recurso deve ser usado quando a situação não cabe em um gatilho nativo simples, preservando legibilidade, tipos e observabilidade.
Tipos comuns de gatilhos
Expressão booleana com múltiplas entidades
A expressão combina estados, como presença em casa, janela aberta e temperatura externa abaixo de 18 °C. O gatilho dispara quando o conjunto passa a ser verdadeiro. Essa abordagem evita criar várias automações intermediárias, mas aumenta acoplamento. Cada entidade precisa ter estados válidos. Um único unavailable pode tornar a expressão false, unknown ou gerar erro, conforme a função. O template deve converter tipos explicitamente e definir padrão seguro. A lista de dependências deve ser detectável pelo motor. Referências dinâmicas construídas por nome podem não ser rastreadas automaticamente, exigindo gatilhos auxiliares ou atualização periódica. A expressão deve ser testada com todas as combinações relevantes, inclusive reinício.
Cálculo derivado e cruzamento lógico
O gatilho pode calcular diferença, média, razão ou balanço. Exemplo: potência solar menos consumo torna-se superior a 1000 W e indica excedente para aquecer água. O cálculo precisa normalizar unidades e proteger divisão por zero. Sensores atualizam em momentos diferentes, criando estados temporariamente inconsistentes. Se um medidor publica produção e outro consumo com segundos de diferença, a diferença pode gerar pico falso. Filtros, janela temporal ou timestamp máximo reduzem. O gatilho é adequado quando o valor derivado é usado apenas nessa regra. Se várias automações precisam dele, um sensor template separado melhora reuso, histórico e diagnóstico.
Template baseado em hora e calendário
A expressão usa now(), dia da semana, data, calendário ou posição solar para produzir verdadeiro em uma janela. A atualização temporal precisa ser conhecida. Alguns motores reavaliam templates de tempo a cada minuto; outros somente quando uma entidade referenciada muda. Uma condição que verifica segundos pode não disparar. Horário de verão, fuso, reinício e eventos que atravessam meia-noite exigem teste. Para horários fixos, gatilho de tempo nativo é preferível porque é explícito e eficiente. Template é útil para regras compostas, como primeiro dia útil após determinada data, desde que a origem de calendário seja confiável e exista reconciliação após indisponibilidade.
Template que interpreta atributos ou payloads complexos
Integrações podem expor listas, dicionários, JSON ou atributos aninhados. O template seleciona elementos e produz uma condição. Uma previsão meteorológica pode disparar quando existe probabilidade superior a 70% nas próximas 3 h; um NVR, quando lista de objetos contém person com confiança acima de 0,8. O schema precisa ser validado. Campos ausentes, lista vazia e mudança de versão não devem causar exceção. Use funções default, checagem de tipo e limites. A expressão deve permanecer específica. Processar payload grande em cada mudança pode consumir CPU. Para fluxo intenso, filtre na integração ou em um processador dedicado.
Template com permanência verdadeira
Algumas plataformas permitem exigir que a expressão permaneça verdadeira por determinado período. O contador começa na transição e é cancelado se o resultado fica falso. Isso filtra condições compostas, como todas as janelas fechadas e umidade acima de 70% por 10 min. A persistência em reinício precisa ser verificada. Se a expressão depende de entidades que atualizam lentamente, um estado obsoleto pode manter o contador. Use timestamps e disponibilidade quando necessário. A duração não é média nem debounce de cada entrada; ela observa o resultado final. A escolha deve refletir dinâmica do processo e intervalo de atualização.
Considerações de Implementação
Conversão implícita de tipos causa resultados silenciosamente errados
Estados frequentemente chegam como strings. Comparar '10' > '2' lexicograficamente pode produzir comportamento diferente da comparação numérica. Valores unknown, unavailable, none e vazio precisam de tratamento. Use conversores como float ou int com default explícito e valide a unidade. Um default zero pode ser perigoso: sensor indisponível pode parecer consumo zero e acionar automação. O padrão seguro depende da ação. Para carga flexível, indisponibilidade deve bloquear. Para alerta de falha, pode disparar fluxo separado. Templates devem falhar de forma visível e registrar contexto, não ocultar erro.
Expressões complexas podem formar dependências invisíveis e loops
Um template pode observar uma entidade que é alterada pela própria ação, voltando a false e true em sequência. Se referências são dinâmicas, o motor pode não saber quando reavaliar. Se a plataforma atualiza a cada minuto, a latência aparece. Evite consulta global de todas as entidades em cada mudança. Divida lógica em sensores derivados e automações menores quando a expressão cresce. Nomeie variáveis e documente unidades. O trace precisa mostrar valores intermediários. Uma regra que só o autor entende aumenta MTTR e risco de mudança futura.
Gatilho template e condição template têm papéis diferentes
O gatilho observa a transição da expressão e inicia a execução. A condição é avaliada depois que outro evento já iniciou. Usar condição não cria um evento quando o valor muda. Usar gatilho para tudo pode gerar muitas avaliações. Exemplo: movimento é gatilho nativo e um template de luminosidade e modo é condição. Em outro caso, excedente solar composto é o evento principal e merece gatilho template. Separar melhora semântica. A escolha deve responder “o que aconteceu?” e “a execução é permitida agora?”.
Teste precisa incluir inicialização e estados indisponíveis
No editor, um template pode produzir true com a casa estável e falhar durante boot, quando entidades carregam em ordem. A automação deve ser testada após reinício completo. Alguns motores não disparam se a expressão inicia true; outros podem. Se o estado desejado precisa ser reconciliado, crie rotina de startup idempotente. Use ferramentas de template, logs e trace. Registre o valor das entradas e o resultado. Teste limites, unidades, lista vazia, timezone e atualização. Um conjunto de casos evita regressão quando integração muda.