{"id":19,"date":"2026-10-04T10:49:15","date_gmt":"2026-10-04T10:49:15","guid":{"rendered":"https:\/\/sfelectronica.com\/bit\/?p=19"},"modified":"2026-10-04T20:15:11","modified_gmt":"2026-10-04T20:15:11","slug":"bomba-de-calor-card-home-assistant","status":"publish","type":"post","link":"https:\/\/sfelectronica.com\/bit\/bomba-de-calor-card-home-assistant\/","title":{"rendered":"Bomba de Calor Card: acompanha a tua instala\u00e7\u00e3o num esquema animado do Home Assistant"},"content":{"rendered":"

O Bomba de Calor Card<\/strong> \u00e9 um cart\u00e3o personalizado (custom card<\/em>) para o Home Assistant que transforma uma imagem t\u00e9cnica da tua instala\u00e7\u00e3o num dashboard vivo: as tubagens ganham fluxo animado, os ventiladores rodam, os dep\u00f3sitos aquecem e cada sensor ocupa exatamente o espa\u00e7o que lhe compete no esquema. \u00c9 um projeto open source, com interface em portugu\u00eas, que se instala por HACS em poucos minutos e dispensa qualquer plugin adicional.<\/p>\n

\n
Projeto<\/span>Bomba de Calor Card<\/span><\/div>\n
Tipo<\/span>Cart\u00e3o Lovelace<\/span><\/div>\n
Instala\u00e7\u00e3o<\/span>HACS ou manual<\/span><\/div>\n
Ficheiro<\/span>bomba-calor-card.js<\/span><\/div>\n
Idiomas<\/span>PT \u00b7 EN \u00b7 ES \u00b7 FR \u00b7 DE<\/span><\/div>\n
Licen\u00e7a<\/span>MIT<\/span><\/div>\n<\/div>\n
\n

Neste artigo<\/p>\n

    \n
  1. Ler valores ou ver a instala\u00e7\u00e3o?<\/a><\/li>\n
  2. O que o cart\u00e3o faz<\/a><\/li>\n
  3. Instala\u00e7\u00e3o por HACS ou manual<\/a><\/li>\n
  4. Configura\u00e7\u00e3o essencial<\/a><\/li>\n
  5. Funcionalidades em detalhe<\/a><\/li>\n
  6. Casos de uso reais<\/a><\/li>\n
  7. Desempenho e boas pr\u00e1ticas<\/a><\/li>\n
  8. Conclus\u00e3o e recursos<\/a><\/li>\n<\/ol>\n<\/div>\n

    O que o cart\u00e3o faz<\/h2>\n

    O Bomba de Calor Card n\u00e3o \u00e9 um gr\u00e1fico est\u00e1tico com sensores por cima. \u00c9 um editor de esquemas completo que corre dentro do Lovelace: defines os pontos de interesse diretamente sobre a imagem, desenhas as tubagens \u00e0 m\u00e3o e associas cada elemento a uma entidade.<\/p>\n

      \n
    • 4<\/strong>Tipos de componentes animados<\/span><\/li>\n
    • 5<\/strong>Estilos de fluxo<\/span><\/li>\n
    • 5<\/strong>Estilos de tanque<\/span><\/li>\n
    • 5<\/strong>Idiomas na interface<\/span><\/li>\n<\/ul>\n
      \n
      \n\t\t01<\/span><\/p>\n

      Editor visual integrado<\/h3>\n

      Configura\u00e7\u00e3o point-and-click<\/em>: clicas na pr\u00e9-visualiza\u00e7\u00e3o para posicionar sensores, bombas e ventiladores, e desenhas os tubos com curvas de B\u00e9zier ajust\u00e1veis.<\/p>\n

      Inclui grelha de alinhamento, reordena\u00e7\u00e3o por arrastar e exporta\u00e7\u00e3o\/importa\u00e7\u00e3o da configura\u00e7\u00e3o completa em JSON.<\/p>\n<\/p><\/div>\n

      \n\t\t02<\/span><\/p>\n

      Gest\u00e3o de entidades<\/h3>\n

      Nome, \u00edcone, cor de texto, cor de \u00edcone e cor de fundo por sensor. Unidade personalizada, multiplicador, casas decimais e op\u00e7\u00e3o de esconder o valor.<\/p>\n

      Com suporte a a\u00e7\u00f5es de clique, visibilidade condicional, alertas intermitentes e cores din\u00e2micas por limiar.<\/p>\n<\/p><\/div>\n

      \n\t\t03<\/span><\/p>\n

      Switches e bot\u00f5es<\/h3>\n

      Um interruptor principal para o atuador da instala\u00e7\u00e3o (bomba de recircula\u00e7\u00e3o, por exemplo) e tantos switches adicionais quantos precisares.<\/p>\n

      Quatro estilos de bot\u00e3o \u2014 padr\u00e3o, quadrado, redondo e transparente \u2014 com cores e textos pr\u00f3prios para cada estado.<\/p>\n<\/p><\/div>\n

      \n\t\t04<\/span><\/p>\n

      Fluxos animados<\/h3>\n

      Cinco estilos de linha (tracejado, pontos, brilho, pulsa\u00e7\u00e3o e cometa), com gradiente entre duas cores para reproduzir aquecimento ou arrefecimento ao longo do tubo.<\/p>\n

      As anima\u00e7\u00f5es podem depender de um estado (on<\/code>) ou de um limiar num\u00e9rico, como pot\u00eancia superior a 20 W.<\/p>\n<\/p><\/div>\n

      \n\t\t05<\/span><\/p>\n

      Componentes din\u00e2micos<\/h3>\n

      Ventiladores com simula\u00e7\u00e3o em perspetiva, bombas circuladoras com rotor animado e suporte a imagens personalizadas, e tanques de \u00e1gua com efeitos distintos.<\/p>\n

      Velocidade, rota\u00e7\u00e3o, inclina\u00e7\u00e3o, opacidade e dimens\u00f5es configur\u00e1veis elemento a elemento.<\/p>\n<\/p><\/div>\n

      \n\t\t06<\/span><\/p>\n

      Efeito de chama<\/h3>\n

      Nos tanques, o estilo fire<\/em> usa um GIF animado com transpar\u00eancia que muda de cor conforme a temperatura e pode crescer ou diminuir de forma proporcional ao valor lido.<\/p>\n

      Ideal para c\u00e2maras de combust\u00e3o, caldeiras de pellets e acumuladores.<\/p>\n<\/p><\/div>\n<\/div>\n

      Ler valores ou ver a instala\u00e7\u00e3o?<\/h2>\n

      Quem tem uma bomba de calor em casa conhece bem o problema: o dashboard enche-se de dezenas de entidades \u2014 temperaturas de ida e retorno, temperatura exterior, press\u00e3o, caudal, consumo el\u00e9trico, estado da bomba de circula\u00e7\u00e3o \u2014 mas nenhuma delas explica o que est\u00e1 a acontecer no sistema. \u00c9 preciso juntar mentalmente meia d\u00fazia de valores para perceber se o dep\u00f3sito de AQS j\u00e1 est\u00e1 quente ou se o permutador est\u00e1 apenas a aquecer o piso.<\/p>\n

      O Bomba de Calor Card resolve isso colocando cada valor no seu contexto f\u00edsico<\/strong>. Em vez de uma lista de sensores, tens o desenho da tua instala\u00e7\u00e3o com os valores sobrepostos, ligados por tubagens animadas que mostram exatamente por onde circula a \u00e1gua e quando.<\/p>\n

      \n
      \"Anima\u00e7\u00e3o
      Cart\u00e3o em funcionamento num dashboard real, com fluxos animados, ventiladores e sensores sobre a imagem de fundo.<\/figcaption><\/figure>\n
      \"Anima\u00e7\u00e3o
      O mesmo cart\u00e3o aplicado a uma caldeira de pellets, com o efeito de chama na c\u00e2mara de combust\u00e3o.<\/figcaption><\/figure>\n<\/div>\n

      O cart\u00e3o n\u00e3o substitui as entidades nem as automatiza\u00e7\u00f5es: \u00e9 uma camada de visualiza\u00e7\u00e3o. Toda a l\u00f3gica continua nos sensores do Home Assistant \u2014 o cart\u00e3o limita-se a reagir ao estado deles. Isso significa que funciona com qualquer integra\u00e7\u00e3o capaz de expor temperaturas, pot\u00eancias e bin\u00e1rios, seja uma bomba de calor comercial, uma caldeira de pellets ou um sistema solar t\u00e9rmico.<\/p>\n

      Instala\u00e7\u00e3o por HACS ou manual<\/h2>\n

      O cart\u00e3o \u00e9 distribu\u00eddo como frontend plugin<\/em>. A via recomendada \u00e9 o HACS<\/strong>, porque passa a receber atualiza\u00e7\u00f5es automaticamente; a instala\u00e7\u00e3o manual serve para instala\u00e7\u00f5es sem HACS ou para testar vers\u00f5es do ficheiro bomba-calor-card.js<\/code>.<\/p>\n

      Via HACS (recomendado)<\/h3>\n
        \n
      1. Confirma que tens o HACS instalado.<\/strong> Se ainda n\u00e3o tens, instala-o primeiro atrav\u00e9s da documenta\u00e7\u00e3o oficial (hacs.xyz).<\/li>\n
      2. Abre o HACS e entra em Frontend<\/em>.<\/strong> O cart\u00e3o n\u00e3o vive na loja de integra\u00e7\u00f5es, mas sim no separador de frontend.<\/li>\n
      3. Abre o menu de tr\u00eas pontos no canto superior direito<\/strong> e escolhe Custom repositories<\/em> (reposit\u00f3rios personalizados).<\/li>\n
      4. Adiciona o URL do reposit\u00f3rio<\/strong> https:\/\/github.com\/sfelectronica\/bomba-calor-card<\/code> e define a categoria como Lovelace<\/strong>.<\/li>\n
      5. Confirma em Add<\/em> e instala o cart\u00e3o<\/strong> a partir da lista. O HACS coloca os ficheiros no s\u00edtio certo por ti.<\/li>\n
      6. Recarrega o dashboard<\/strong> (Ctrl+F5) e o cart\u00e3o passa a aparecer no seletor \u00abAdicionar cart\u00e3o\u00bb.<\/li>\n<\/ol>\n
        \n\tOK<\/span><\/p>\n

        Existe um bot\u00e3o Open in HACS<\/strong> no README do projeto. Se abrires esse link a partir do Home Assistant, os passos 2 a 5 s\u00e3o feitos automaticamente pelo redirecionador my.home-assistant.io<\/code>.<\/p>\n<\/div>\n

        Instala\u00e7\u00e3o manual<\/h3>\n
          \n
        1. Descarrega o ficheiro bomba-calor-card.js<\/code><\/strong> a partir da p\u00e1gina de releases ou do pr\u00f3prio reposit\u00f3rio.<\/li>\n
        2. Coloca-o em \/config\/www\/community\/bomba-calor-card\/<\/code><\/strong>, criando as pastas que ainda n\u00e3o existam (\u00e9 acess\u00edvel por SSH, SAMBA ou pelo add-on de ficheiros).<\/li>\n
        3. Regista o recurso<\/strong> no Lovelace: pela interface, em Defini\u00e7\u00f5es \u2192 Dashboards \u2192 \u22ee \u2192 Recursos<\/em>, ou em modo YAML conforme o exemplo abaixo.<\/li>\n<\/ol>\n
          lovelace:\r\n  resources:\r\n    - url: \/local\/community\/bomba-calor-card\/bomba-calor-card.js\r\n      type: module<\/code><\/pre>\n
          \n\t!<\/span><\/p>\n
          A pasta \/config\/www\/<\/code> corresponde ao URL \/local\/<\/code>. Se o caminho do recurso n\u00e3o bater certo com o s\u00edtio onde o ficheiro est\u00e1, o cart\u00e3o aparece como \u00abCustom element doesn’t exist: bomba-calor-card\u00bb.<\/p>\n<\/div>\n
          Imagem de fundo<\/h3>\n
          Por omiss\u00e3o, o cart\u00e3o procura a imagem em \/local\/cardbomba.jpg<\/code>. Podes fazer upload da tua pr\u00f3pria fotografia t\u00e9cnica para a pasta www<\/code> e indicar o caminho no editor visual, ou usar as imagens de exemplo que acompanham o projeto.<\/p>\n
          \n
          \"Ilustra\u00e7\u00e3o
          BombaGold.png: dep\u00f3sito de AQS, bomba de circula\u00e7\u00e3o e m\u00f3dulo de controlo j\u00e1 desenhados.<\/figcaption><\/figure>\n
          \"Ilustra\u00e7\u00e3o
          pumpgold.png: imagem de bomba circuladora pronta a animar com o estado de um interruptor.<\/figcaption><\/figure>\n<\/div>\n
          Configura\u00e7\u00e3o essencial<\/h2>\n
          H\u00e1 dois caminhos para configurar o cart\u00e3o. O normal \u00e9 usar o editor visual<\/strong>: adicionas o cart\u00e3o ao dashboard, abres o editor e posicionas os elementos com o rato. O segundo caminho \u00e9 escrever a configura\u00e7\u00e3o em YAML, \u00fatil para manter tudo em ficheiros versionados ou para replicar o mesmo esquema em v\u00e1rios dashboards.<\/p>\n
          Em qualquer dos casos, a estrutura \u00e9 a mesma: uma imagem de fundo, as coordenadas em percentagem relativas \u00e0 view box<\/em> e listas indexadas de elementos.<\/p>\n
          type: custom:bomba-calor-card\r\nimage: \/local\/cardbomba.jpg\r\nlanguage: auto            # auto | pt | en | es | fr | de\r\nview_box: \"0 0 100 180\"   # sistema de coordenadas sobre a imagem\r\nbadge_opacity: 0.4\r\nlow_performance: false\r\n\r\n# --- Sensores (as listas s\u00e3o paralelas: \u00edndice 0 de cada lista = mesmo sensor) ---\r\nentities:\r\n  - sensor.aqs_temperatura\r\n  - sensor.retorno_temperatura\r\n  - sensor.exterior_temperatura\r\nnames:\r\n  - AQS\r\n  - Retorno\r\n  - Exterior\r\nicons:\r\n  - mdi:water-thermometer\r\n  - mdi:thermometer\r\n  - mdi:weather-snowy\r\npositions:\r\n  - { left: 55, top: 28 }\r\n  - { left: 32, top: 60 }\r\n  - { left: 8,  top: 12 }\r\ndecimals: [1, 1, 1]\r\n\r\n# --- Tubagens animadas ---\r\nanimations:\r\n  - entity: binary_sensor.bomba_circuladora\r\n    path: M 32,60 L 55,60 L 55,28\r\n    color: \"#2681DC\"\r\n    color_end: \"#ff3b30\"\r\n    style: dashes          # dashes | dots | shimmer | pulse | comet\r\n    dash: \"10 5\"\r\n    width: 2\r\n    speed: 1.5\r\n    threshold: 20          # s\u00f3 anima acima de 20 W\r\n\r\n# --- Ventiladores e bombas ---\r\nfans:\r\n  - entity: switch.ventilador_evaporador\r\n    x: 78\r\n    y: 22\r\n    size: 14\r\n    tilt: 0.6\r\n    skew: 0.2\r\n    reverse: false\r\n\r\npumps:\r\n  - entity: switch.bomba_recirculacao\r\n    x: 32\r\n    y: 60\r\n    size: 12\r\n    color: \"#ff7a18\"\r\n\r\n# --- Tanque com efeito de chama proporcional \u00e0 temperatura ---\r\nwater_tanks:\r\n  - x: 55\r\n    y: 28\r\n    width: 16\r\n    height: 30\r\n    opacity: 0.5\r\n    style: fire            # bubbles | waves | ripple | fire | jet\r\n    temp_entity: sensor.aqs_temperatura\r\n    min_temp: 30\r\n    max_temp: 75\r\n    min_color: \"#2681DC\"\r\n    max_color: \"#ff3b30\"\r\n    interactive_flame: true\r\n    fire_image: \/local\/community\/bomba-calor-card\/fire.gif\r\n\r\n# --- Interruptor principal e interruptores extra ---\r\nswitch: switch.degelo\r\nswitch_position: { left: 10, top: 50 }\r\nswitch_style: default      # default | square | round | transparent\r\nswitch_text_on: Degelo\r\nswitch_text_off: Normal\r\nswitches:\r\n  - entity: switch.bomba_secundaria\r\n    name: Secund\u00e1rio\r\n    left: 10\r\n    top: 70<\/code><\/pre>\n
          \n\ti<\/span><\/p>\n
          Listas paralelas:<\/strong> em entities<\/code>, names<\/code>, icons<\/code>, positions<\/code>, colors<\/code>, units<\/code> ou decimals<\/code>, cada lista descreve os mesmos sensores pela mesma ordem. O elemento 0<\/code> de todas as listas pertence ao primeiro sensor, e assim sucessivamente. Se acrescentares um sensor no fim, basta acrescentar uma entrada no fim de cada lista.<\/p>\n<\/div>\n
          Funcionalidades em detalhe<\/h2>\n
          Entidades: formata\u00e7\u00e3o e comportamento<\/h3>\n
          Cada sensor tem uma ficha pr\u00f3pria. Al\u00e9m do nome e do \u00edcone, podes substituir a unidade de medida original (por exemplo, mostrar Watts<\/code> em vez de W<\/code>, ou remover a unidade), aplicar um multiplicador para fazer convers\u00f5es como W → kW, definir o n\u00famero de casas decimais e esconder o valor para mostrar apenas o \u00edcone.<\/p>\n
          H\u00e1 ainda tr\u00eas comportamentos que fazem a diferen\u00e7a no dia a dia:<\/p>\n
            \n
          • Visibilidade condicional<\/strong> \u2014 esconder uma entidade com base no estado de outra. A temperatura dos pain\u00e9is solares s\u00f3 aparece, por exemplo, quando a bomba solar est\u00e1 ligada.<\/li>\n
          • Alerta por limiar<\/strong> \u2014 o badge da entidade come\u00e7a a piscar quando o valor ultrapassa o limite definido, o que torna imediatos os avisos de sobreaquecimento ou de press\u00e3o baixa.<\/li>\n
          • Cores din\u00e2micas<\/strong> \u2014 o \u00edcone muda de cor conforme o valor: azul abaixo dos 10 \u00b0C, vermelho acima dos 60 \u00b0C, por exemplo, com limiares e cores configur\u00e1veis.<\/li>\n<\/ul>\n
            Cada entidade aceita tamb\u00e9m tap actions<\/em>: abrir a janela de mais informa\u00e7\u00f5es, alternar o estado (toggle<\/code>), navegar para outro dashboard ou chamar diretamente um servi\u00e7o. Na pr\u00e1tica, o esquema passa a ser tamb\u00e9m uma interface de controlo.<\/p>\n
            Anima\u00e7\u00f5es de fluxo nas tubagens<\/h3>\n
            As tubagens s\u00e3o desenhadas com curvas de B\u00e9zier e animadas por stroke-dash<\/em>, o que resulta em anima\u00e7\u00f5es suaves mesmo em dispositivos modestos. Existem cinco estilos:<\/p>\n\n\n\n\n\n\n\n\n\n
            Estilo<\/th>\nEfeito<\/th>\nOnde brilha<\/th>\n<\/tr>\n<\/thead>\n
            dashes<\/code><\/td>\nTra\u00e7os em movimento, tipo corrente<\/td>\nCircuitos hidr\u00e1ulicos de \u00e1gua quente<\/td>\n<\/tr>\n
            dots<\/code><\/td>\nPontos espa\u00e7ados<\/td>\nFluxos de baixo caudal ou gotejar<\/td>\n<\/tr>\n
            shimmer<\/code><\/td>\nBrilho que percorre a linha<\/td>\nReal\u00e7ar o sentido do retorno<\/td>\n<\/tr>\n
            pulse<\/code><\/td>\nPulsa\u00e7\u00e3o cont\u00ednua<\/td>\nIndicar troca de calor ativa<\/td>\n<\/tr>\n
            comet<\/code><\/td>\nRasto luminoso com cauda<\/td>\nCr\u00e9dito visual m\u00e1ximo no dashboard<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
            Com color<\/code> e color_end<\/code> defines um gradiente ao longo do tubo, o que permite mostrar a \u00e1gua a arrefecer entre a ida e o retorno. A anima\u00e7\u00e3o pode depender de um estado simples (state_on<\/code>, tipicamente on<\/code>) ou de um limiar num\u00e9rico<\/strong> passado em threshold<\/code> \u2014 por exemplo, animar apenas quando a bomba consome mais de 20 W.<\/p>\n
            Ventiladores, bombas e tanques<\/h3>\n
            Os ventiladores<\/strong> t\u00eam simula\u00e7\u00e3o tridimensional atrav\u00e9s dos par\u00e2metros de inclina\u00e7\u00e3o (tilt<\/code>) e perspetiva (skew<\/code>), rota\u00e7\u00e3o com velocidade ajust\u00e1vel e possibilidade de inverter o sentido. As bombas circuladoras<\/strong> mostram um rotor animado e aceitam imagens personalizadas \u2014 podes carregar o desenho da tua pr\u00f3pria bomba, que roda conforme o estado do interruptor associado.<\/p>\n
            Os tanques de \u00e1gua<\/strong> s\u00e3o o elemento mais expressivo. Existem cinco estilos visuais:<\/p>\n