Bomba de Calor Card: acompanha a tua instalação num esquema animado do Home Assistant

O Bomba de Calor Card é um cartão personalizado (custom card) para o Home Assistant que transforma uma imagem técnica da tua instalação num dashboard vivo: as tubagens ganham fluxo animado, os ventiladores rodam, os depósitos aquecem e cada sensor ocupa exatamente o espaço que lhe compete no esquema. É um projeto open source, com interface em português, que se instala por HACS em poucos minutos e dispensa qualquer plugin adicional.

O que o cartão faz

O Bomba de Calor Card não é um gráfico estático com sensores por cima. É um editor de esquemas completo que corre dentro do Lovelace: defines os pontos de interesse diretamente sobre a imagem, desenhas as tubagens à mão e associas cada elemento a uma entidade.

• 4Tipos de componentes animados
• 5Estilos de fluxo
• 5Estilos de tanque
• 5Idiomas na interface

Ler valores ou ver a instalação?

Quem tem uma bomba de calor em casa conhece bem o problema: o dashboard enche-se de dezenas de entidades — temperaturas de ida e retorno, temperatura exterior, pressão, caudal, consumo elétrico, estado da bomba de circulação — mas nenhuma delas explica o que está a acontecer no sistema. É preciso juntar mentalmente meia dúzia de valores para perceber se o depósito de AQS já está quente ou se o permutador está apenas a aquecer o piso.

O Bomba de Calor Card resolve isso colocando cada valor no seu contexto físico. Em vez de uma lista de sensores, tens o desenho da tua instalação com os valores sobrepostos, ligados por tubagens animadas que mostram exatamente por onde circula a água e quando.

O cartão não substitui as entidades nem as automatizações: é uma camada de visualização. Toda a lógica continua nos sensores do Home Assistant — o cartão limita-se a reagir ao estado deles. Isso significa que funciona com qualquer integração capaz de expor temperaturas, potências e binários, seja uma bomba de calor comercial, uma caldeira de pellets ou um sistema solar térmico.

Instalação por HACS ou manual

O cartão é distribuído como frontend plugin. A via recomendada é o HACS, porque passa a receber atualizações automaticamente; a instalação manual serve para instalações sem HACS ou para testar versões do ficheiro bomba-calor-card.js.

Via HACS (recomendado)

1. Confirma que tens o HACS instalado. Se ainda não tens, instala-o primeiro através da documentação oficial (hacs.xyz).
2. Abre o HACS e entra em Frontend. O cartão não vive na loja de integrações, mas sim no separador de frontend.
3. Abre o menu de três pontos no canto superior direito e escolhe Custom repositories (repositórios personalizados).
4. Adiciona o URL do repositório https://github.com/sfelectronica/bomba-calor-card e define a categoria como Lovelace.
5. Confirma em Add e instala o cartão a partir da lista. O HACS coloca os ficheiros no sítio certo por ti.
6. Recarrega o dashboard (Ctrl+F5) e o cartão passa a aparecer no seletor «Adicionar cartão».

Instalação manual

1. Descarrega o ficheiro bomba-calor-card.js a partir da página de releases ou do próprio repositório.
2. Coloca-o em /config/www/community/bomba-calor-card/, criando as pastas que ainda não existam (é acessível por SSH, SAMBA ou pelo add-on de ficheiros).
3. Regista o recurso no Lovelace: pela interface, em Definições → Dashboards → ⋮ → Recursos, ou em modo YAML conforme o exemplo abaixo.

lovelace:
  resources:
    - url: /local/community/bomba-calor-card/bomba-calor-card.js
      type: module

Imagem de fundo

Por omissão, o cartão procura a imagem em /local/cardbomba.jpg. Podes fazer upload da tua própria fotografia técnica para a pasta www e indicar o caminho no editor visual, ou usar as imagens de exemplo que acompanham o projeto.

Configuração essencial

Há dois caminhos para configurar o cartão. O normal é usar o editor visual: adicionas o cartão ao dashboard, abres o editor e posicionas os elementos com o rato. O segundo caminho é escrever a configuração em YAML, útil para manter tudo em ficheiros versionados ou para replicar o mesmo esquema em vários dashboards.

Em qualquer dos casos, a estrutura é a mesma: uma imagem de fundo, as coordenadas em percentagem relativas à view box e listas indexadas de elementos.

type: custom:bomba-calor-card
image: /local/cardbomba.jpg
language: auto            # auto | pt | en | es | fr | de
view_box: "0 0 100 180"   # sistema de coordenadas sobre a imagem
badge_opacity: 0.4
low_performance: false

# --- Sensores (as listas são paralelas: índice 0 de cada lista = mesmo sensor) ---
entities:
  - sensor.aqs_temperatura
  - sensor.retorno_temperatura
  - sensor.exterior_temperatura
names:
  - AQS
  - Retorno
  - Exterior
icons:
  - mdi:water-thermometer
  - mdi:thermometer
  - mdi:weather-snowy
positions:
  - { left: 55, top: 28 }
  - { left: 32, top: 60 }
  - { left: 8,  top: 12 }
decimals: [1, 1, 1]

# --- Tubagens animadas ---
animations:
  - entity: binary_sensor.bomba_circuladora
    path: M 32,60 L 55,60 L 55,28
    color: "#2681DC"
    color_end: "#ff3b30"
    style: dashes          # dashes | dots | shimmer | pulse | comet
    dash: "10 5"
    width: 2
    speed: 1.5
    threshold: 20          # só anima acima de 20 W

# --- Ventiladores e bombas ---
fans:
  - entity: switch.ventilador_evaporador
    x: 78
    y: 22
    size: 14
    tilt: 0.6
    skew: 0.2
    reverse: false

pumps:
  - entity: switch.bomba_recirculacao
    x: 32
    y: 60
    size: 12
    color: "#ff7a18"

# --- Tanque com efeito de chama proporcional à temperatura ---
water_tanks:
  - x: 55
    y: 28
    width: 16
    height: 30
    opacity: 0.5
    style: fire            # bubbles | waves | ripple | fire | jet
    temp_entity: sensor.aqs_temperatura
    min_temp: 30
    max_temp: 75
    min_color: "#2681DC"
    max_color: "#ff3b30"
    interactive_flame: true
    fire_image: /local/community/bomba-calor-card/fire.gif

# --- Interruptor principal e interruptores extra ---
switch: switch.degelo
switch_position: { left: 10, top: 50 }
switch_style: default      # default | square | round | transparent
switch_text_on: Degelo
switch_text_off: Normal
switches:
  - entity: switch.bomba_secundaria
    name: Secundário
    left: 10
    top: 70

Funcionalidades em detalhe

Entidades: formatação e comportamento

Cada sensor tem uma ficha própria. Além do nome e do ícone, podes substituir a unidade de medida original (por exemplo, mostrar Watts em vez de W, ou remover a unidade), aplicar um multiplicador para fazer conversões como W → kW, definir o número de casas decimais e esconder o valor para mostrar apenas o ícone.

Há ainda três comportamentos que fazem a diferença no dia a dia:

• Visibilidade condicional — esconder uma entidade com base no estado de outra. A temperatura dos painéis solares só aparece, por exemplo, quando a bomba solar está ligada.
• Alerta por limiar — o badge da entidade começa a piscar quando o valor ultrapassa o limite definido, o que torna imediatos os avisos de sobreaquecimento ou de pressão baixa.
• Cores dinâmicas — o ícone muda de cor conforme o valor: azul abaixo dos 10 °C, vermelho acima dos 60 °C, por exemplo, com limiares e cores configuráveis.

Cada entidade aceita também tap actions: abrir a janela de mais informações, alternar o estado (toggle), navegar para outro dashboard ou chamar diretamente um serviço. Na prática, o esquema passa a ser também uma interface de controlo.

Animações de fluxo nas tubagens

As tubagens são desenhadas com curvas de Bézier e animadas por stroke-dash, o que resulta em animações suaves mesmo em dispositivos modestos. Existem cinco estilos:

Com color e color_end defines um gradiente ao longo do tubo, o que permite mostrar a água a arrefecer entre a ida e o retorno. A animação pode depender de um estado simples (state_on, tipicamente on) ou de um limiar numérico passado em threshold — por exemplo, animar apenas quando a bomba consome mais de 20 W.

Ventiladores, bombas e tanques

Os ventiladores têm simulação tridimensional através dos parâmetros de inclinação (tilt) e perspetiva (skew), rotação com velocidade ajustável e possibilidade de inverter o sentido. As bombas circuladoras mostram um rotor animado e aceitam imagens personalizadas — podes carregar o desenho da tua própria bomba, que roda conforme o estado do interruptor associado.

Os tanques de água são o elemento mais expressivo. Existem cinco estilos visuais:

• Bubbles — bolhas em movimento dentro do tanque.
• Waves — ondulação na superfície do líquido.
• Ripple — ondas concêntricas que se propagam.
• Fire — chama a partir de um GIF com transparência, com coloração dinâmica entre min_color e max_color e a largura da chama a crescer com a temperatura quando interactive_flame está ativo.
• Jet — jato de partículas, para silos, depósitos de pellets ou fluxo de ar, com modo inverso para simular aspiração.

Cada elemento aceita rotação, opacidade, dimensões e cores próprias, o que permite alinhar o esquema com fotografias reais da instalação.

Editor visual e segurança da configuração

O editor permite clicar diretamente na imagem para posicionar elementos, arrastar entidades para reordenar a lista, desenhar caminhos curvos ponto a ponto e ajustar a tensão das curvas, tudo com uma grelha auxiliar de alinhamento.

A configuração completa pode ser exportada e importada em JSON, funcionando como cópia de segurança: se alterares o cartão e não gostares do resultado, voltas atrás num clique. A interface do editor está traduzida em português, inglês, espanhol, francês e alemão.

Casos de uso reais

Como o cartão trabalha sobre uma imagem que escolhes, adapta-se a praticamente qualquer instalação térmica. Estes são os cenários onde o retorno é maior:

• Bomba de calor com AQS e piso radiante — o caso clássico. O depósito de águas quentes sanitárias fica identificado com um tanque, a ida e o retorno dos circuitos com tubagens em gradiente de cor, e a bomba de circulação com um componente animado que roda quando consome energia.
• Caldeira de pellets ou biomassa — câmara de combustão com estilo fire, silo com efeito jet e sensores de temperatura dos fumos no esquema. O exemplo de pré-visualização do repositório mostra exatamente este cenário.
• Solar térmico com apoio — a visibilidade condicional evita poluição visual: as temperaturas dos painéis e do permutador só aparecem quando a bomba solar está em funcionamento.
• Monitorização de consumos — com o multiplicador e as casas decimais, mostras potência em kW diretamente sobre o desenho, e o alerta intermitente avisa quando a resistência elétrica de apoio entra em serviço.

O único requisito é a imagem de fundo. Uma fotografia frontal de qualidade média, um recorte técnico do manual ou mesmo um desenho vetorial simples servem; o que importa é que os componentes fiquem nas posições corretas para que os fluxos façam sentido.

Desempenho e boas práticas

Um esquema animado corre sempre em cima do dashboard, por isso vale a pena ter em conta quatro pontos:

1. Otimiza a imagem de fundo. É o fator com mais peso. Uma imagem entre 1000 e 1400 px de largura, em JPG ou WebP e abaixo de 400 KB, é mais do que suficiente para ecrãs comuns.
2. Usa o modo de baixo desempenho quando necessário. A opção low_performance desativa os efeitos mais pesados (desfoques) e mantém as animações fluídas em Raspberry Pi e tablets antigos.
3. Prefere limiares a estados vazios. Em vez de animar sempre, usa threshold para que os fluxos só apareçam quando existe consumo real — o dashboard fica mais informativo e menos ruidoso.
4. Guarda a configuração em JSON. Antes de alterações grandes, exporta a configuração: qualquer experiência fica reversível em segundos.

Conclusão

O Bomba de Calor Card preenche uma lacuna concreta do Home Assistant: transformar dados térmicos dispersos numa representação visual que se percebe num relance. Não substitui o trabalho de integração nem a configuração das entidades — é, isso sim, a camada que faltava por cima delas.

O projeto está publicado sob licença MIT, com documentação em português e inglês, e distribui-se como plugin de frontend na categoria Lovelace do HACS. Podes usá-lo, modificá-lo e distribuí-lo livremente, sem garantias por parte do autor.