Automações

Condição por Template

Para decidir se uma execução pode prosseguir quando a regra envolve várias fontes, a condição por template avalia uma expressão e converte o resultado em verdadeiro ou falso. Em Home Assistant, Jinja permite combinar presença, horários, atributos, cálculos e disponibilidade. É preferível à condição numérica nativa quando há relações complexas, mas aumenta acoplamento e risco de erro de tipo. Templates devem tratar unknown, unidades, dados antigos e reinício, além de permanecer legíveis no trace.


⚙ Definição Técnica
Condição por template é um predicado programável executado em um ponto da automação para decidir se o fluxo continua, usando uma expressão que pode ler estados, atributos, variáveis, funções, tempo e resultados de etapas anteriores. Ela não monitora continuamente a expressão nem cria evento; a renderização ocorre quando o motor alcança a condição, salvo quando uma plataforma implementa semântica diferente. O resultado precisa ser convertido de forma inequívoca em booleano, com tratamento explícito de tipos, indisponibilidade, unidades, dados antigos e exceções.
Tipos comuns de gatilhos
Condição composta de contexto
A expressão combina presença, modo da casa, horário, estado de abertura e outras informações que não cabem em um único comparador. Uma regra de climatização pode prosseguir apenas quando há alguém em casa, nenhuma janela está aberta e o modo não é férias. O benefício é expressar uma política em um único ponto. O custo é legibilidade. AND, OR e NOT precisam estar agrupados de maneira clara. Parênteses implícitos e precedência podem produzir resultado diferente do esperado. Em vez de uma linha longa, use variáveis nomeadas ou sensores derivados. O trace deve mostrar valores de cada componente. A expressão precisa definir comportamento para uma entidade unavailable; em ações de conforto, bloquear costuma ser seguro, mas a política deve ser declarada.
Condição baseada em cálculo entre entidades
O template calcula relação, diferença, média ou tendência antes de decidir. Exemplo: permitir aquecimento de água somente se geração solar menos consumo da casa for superior a 1,5 kW e a bateria estiver acima de 60%. As fontes podem atualizar em tempos distintos, criando valor inconsistente. A condição deve verificar frescor dos timestamps ou usar uma entidade agregada. Unidades precisam ser normalizadas. W e kW não podem ser somados diretamente. Valores negativos, ausentes e limites físicos devem ser tratados. Se a fórmula é reutilizada, um sensor template melhora histórico e evita duplicação. A condição permanece adequada quando o cálculo é local a um único fluxo.
Condição sobre payload e variáveis do gatilho
Eventos MQTT, webhooks e integrações fornecem objetos estruturados. A condição pode validar event_type, device_id, confiança, assinatura já verificada ou campos do payload. Um NVR pode permitir a ação apenas quando object_class é person e confidence >= 0,85. O template precisa tratar lista vazia, campo ausente e tipo inesperado. Dados externos não são confiáveis por padrão. A validação de segurança deve ocorrer antes, na integração ou no gateway. O template decide lógica de negócio, não substitui autenticação. Valores usados para selecionar serviços devem passar por allowlist. Nunca monte nomes de serviço arbitrários diretamente de payload sem restrição.
Condição temporal avançada
A expressão verifica calendário, feriado, janela que cruza meia-noite, dia útil ou distância para nascer do sol. Regras simples devem usar condições temporais nativas. Template é útil quando a lógica é composta. Fuso horário, horário de verão e timestamps UTC exigem atenção. Uma janela 22:00–06:00 precisa usar OR, não comparação simples de intervalo no mesmo dia. Calendários podem ficar indisponíveis. Eventos de dia inteiro têm semântica própria. A condição deve usar a timezone configurada e evitar strings localizadas. Para ações críticas, relógio e sincronização NTP são dependências. Após reinício, valores de calendário precisam ser recarregados antes da avaliação.
Condição de disponibilidade e qualidade do dado
O template não avalia apenas o valor, mas se a fonte está disponível, recente e dentro de limites plausíveis. Uma bomba pode ser autorizada somente quando o sensor de nível está online, atualizado há menos de 60 s e entre 0 e 100%. Esse padrão evita que um número restaurado antigo pareça válido. A expressão pode conferir last_updated, quality flag e status da integração. O risco é criar dependência de atributos internos que mudam. Quando a qualidade é requisito sistêmico, convém criar entidade binária de health. A condição fica mais simples e múltiplas automações compartilham a mesma política.
Considerações de Implementação
⚠️
Defaults convenientes podem transformar falha em permissão
Converter unavailable para 0 é comum e perigoso. Se a condição é potência abaixo de 5 W, sensor indisponível convertido para zero libera a ação. Defaults devem refletir estado seguro. Para permissões, ausência normalmente deve resultar false. Para alertas, ausência pode ser true em um fluxo separado. Use funções de conversão com default explícito e teste. Não capture exceções retornando verdadeiro. Erros de template precisam aparecer em logs e trace. A plataforma deve diferenciar condição falsa de falha de renderização, porque as respostas operacionais são distintas.
⚠️
Template complexo aumenta risco de regressão e manutenção
Expressões longas com múltiplas funções, loops e referências dinâmicas tornam-se difíceis de revisar. Mudança no nome de entidade, atributo ou unidade pode quebrar silenciosamente. Extraia cálculos para sensores derivados, use helpers para parâmetros e documente. Evite duplicar a mesma lógica em várias regras. Teste casos de limite, ausência, reinício e timezone. Controle de versão e revisão ajudam. A linguagem de template é poderosa, mas não é substituto para arquitetura. Quando a lógica vira programa, um script ou componente testável pode ser mais adequado.
ℹ️
A condição é avaliada no instante em que o fluxo chega
A automação pode esperar, executar ações e só depois avaliar. O estado pode ter mudado desde o gatilho. Isso pode ser desejado. Se a decisão deve usar snapshot original, capture variáveis no início. Se deve refletir realidade atual, reavalie. Exemplo: após atraso de 5 min, verificar novamente presença evita apagar luz com alguém no ambiente. Para auditoria, registre ambos quando relevante. Modos paralelos podem ter snapshots diferentes. A semântica temporal precisa ser consciente.
ℹ️
Trace e testes de casos são parte da definição
Um template sem observabilidade é difícil de operar. O trace deve preservar texto renderizado, booleano, variáveis e erro. Para segurança, redija segredos. Crie tabela de casos: presença on/off, janela open/closed, sensor unavailable, limite exato, horário antes/depois. Execute no editor e em reinício. Teste também valores como 'unknown', null e strings. Atualizações da plataforma podem alterar filtros e tipos. Uma pequena suíte de casos documentada reduz falhas futuras.