{"id":26,"date":"2026-10-05T09:16:22","date_gmt":"2026-10-05T09:16:22","guid":{"rendered":"https:\/\/sfelectronica.com\/bit\/?p=26"},"modified":"2026-10-05T13:28:44","modified_gmt":"2026-10-05T13:28:44","slug":"automacao-portao-esphome-home-assistant","status":"publish","type":"post","link":"https:\/\/sfelectronica.com\/bit\/automacao-portao-esphome-home-assistant\/","title":{"rendered":"Automa\u00e7\u00e3o de Port\u00e3o com ESPHome e Home Assistant"},"content":{"rendered":"\n

O ESPPortao<\/strong> transforma um port\u00e3o de garagem convencional num dispositivo inteligente, sem trocar o motor nem o comando original: um ESP8266<\/strong> a correr ESPHome<\/strong> simula os bot\u00f5es do controlo remoto por rel\u00e9, l\u00ea tr\u00eas sensores de fim de curso e exp\u00f5e o port\u00e3o ao Home Assistant<\/strong> como uma entidade cover<\/em> nativa. Abertura total, abertura pedonal, estado em tempo real e ilumina\u00e7\u00e3o exterior \u2014 tudo local, sem nuvem e sem subscri\u00e7\u00f5es.<\/p>\n\n\n\n

\r\n\r\n\t
Projeto<\/span>ESPPortao<\/span><\/div>\r\n\r\n\t
Hardware<\/span>ESP8266 \u00b7 m\u00f3dulo rel\u00e9 \u00d73 \u00b7 fim de curso \u00d73<\/span><\/div>\r\n\r\n\t
Firmware<\/span>ESPHome (min. 2024.6.0)<\/span><\/div>\r\n\r\n\t
Plataforma<\/span>Home Assistant<\/span><\/div>\r\n\r\n\t
Ficheiro<\/span>portao.yaml<\/span><\/div>\r\n\r\n\t
Rede<\/span>IP est\u00e1tico \u00b7 AP + captive portal<\/span><\/div>\r\n\r\n\t
Nuvem<\/span>Nenhuma \u2014 100% local<\/span><\/div>\r\n\r\n<\/div>\n\n\n\n
\r\n\r\n\t

Neste artigo<\/p>\r\n\r\n\t

    \r\n\r\n\t\t
  1. Vis\u00e3o geral do sistema<\/a><\/li>\r\n\r\n\t\t
  2. Hardware e esquema de liga\u00e7\u00e3o<\/a><\/li>\r\n\r\n\t\t
  3. Mapeamento dos GPIO<\/a><\/li>\r\n\r\n\t\t
  4. O YAML, bloco a bloco<\/a><\/li>\r\n\r\n\t\t
  5. Rede, gest\u00e3o e atualiza\u00e7\u00f5es<\/a><\/li>\r\n\r\n\t\t
  6. Instala\u00e7\u00e3o passo a passo<\/a><\/li>\r\n\r\n\t\t
  7. No Home Assistant<\/a><\/li>\r\n\r\n\t\t
  8. Diagn\u00f3stico e boas pr\u00e1ticas<\/a><\/li>\r\n\r\n\t\t
  9. Conclus\u00e3o<\/a><\/li>\r\n\r\n\t<\/ol>\r\n\r\n<\/div>\n\n\n\n

    Vis\u00e3o geral do sistema<\/h2>\n\n\n\n

    A ideia \u00e9 simples: em vez de comprar um kit de automa\u00e7\u00e3o fechado, usa-se o pr\u00f3prio comando do port\u00e3o<\/strong>. O microcontrolador fecha os contactos dos bot\u00f5es abrir\/fechar<\/em> e parcial<\/em> exatamente como faria o telemando, e tr\u00eas sensores de fim de curso dizem onde o port\u00e3o est\u00e1 em cada momento. O resultado \u00e9 um sistema h\u00edbrido \u2014 o port\u00e3o continua a funcionar com o comando original, e o ESPHome acrescenta controlo remoto, automa\u00e7\u00f5es e monitoriza\u00e7\u00e3o.<\/p>\n\n\n\n

      \n
    • 3<\/strong>Sa\u00eddas rel\u00e9: passo completo, parcial e luz<\/span><\/li>\n\n\n\n
    • 3<\/strong>Sensores de fim de curso com filtro anti-vibra\u00e7\u00e3o<\/span><\/li>\n\n\n\n
    • 1 s<\/strong>Pulso moment\u00e2neo com interlock entre rel\u00e9s<\/span><\/li>\n\n\n\n
    • 0<\/strong>Servi\u00e7os externos ou depend\u00eancia da nuvem<\/span><\/li>\n<\/ul>\n\n\n\n

      A entidade central \u00e9 um cover<\/code> template<\/strong> com device_class: gate<\/code>. Isto significa que no Home Assistant o port\u00e3o aparece com o \u00edcone, os estados e os comandos certos: abre, fecha, para a meio caminho, participa em dashboards, aparece no Voice Assist e pode ser usado em qualquer automa\u00e7\u00e3o como qualquer port\u00e3o inteligente de fabricante.<\/p>\n\n\n\n

      Hardware e esquema de liga\u00e7\u00e3o<\/h2>\n\n\n\n

      N\u00e3o h\u00e1 nada ex\u00f3tico na lista de materiais. Tudo cabe numa pequena caixa de embutir junto \u00e0 central do port\u00e3o, alimentado por uma fonte de 5 V:<\/p>\n\n\n\n

        \n
      • Placa ESP8266<\/strong> \u2014 o YAML declara board: esp01_1m<\/code>; na pr\u00e1tica, use uma placa com os pins expostos (NodeMCU ou Wemos D1 mini).<\/li>\n\n\n\n
      • M\u00f3dulo rel\u00e9 de 3 canais<\/strong> \u2014 opto-isolado, com sa\u00edda NO\/NC, para simular os bot\u00f5es do comando e comandar a luz exterior.<\/li>\n\n\n\n
      • 3 bot\u00f5es fim de curso<\/strong> (normalmente abertos) \u2014 um no fim de curso de fechado, um na posi\u00e7\u00e3o interm\u00e9dia e um no fim de curso de aberto.<\/li>\n\n\n\n
      • Fonte de 5\u00a0V DC<\/strong> \u2014 USB ou regulador, consoante o s\u00edtio de instala\u00e7\u00e3o.<\/li>\n\n\n\n
      • Caixa de embutir<\/strong> e cabo de liga\u00e7\u00e3o ao comando existente.<\/li>\n<\/ul>\n\n\n\n
        \"Esquema
        Liga\u00e7\u00e3o completa: ESP8266 no centro, rel\u00e9s \u00e0 direita, fins de curso \u00e0 esquerda<\/figcaption><\/figure>\n\n\n\n
        \r\n\t!<\/span>\r\n\t

        Nota de hardware:<\/strong> o ficheiro usa esp8266: board: esp01_1m<\/code>, mas os seis GPIO referenciados (GPIO4, 5, 12, 13, 14 e 16) n\u00e3o existem num ESP-01, que s\u00f3 exp\u00f5e GPIO0 e GPIO2. Usa antes uma placa NodeMCU ou Wemos D1 mini \u2014 a configura\u00e7\u00e3o \u00e9 id\u00eantica e tens todos os pins \u00e0 m\u00e3o.<\/p>\r\n\t

        Trabalha sempre com o port\u00e3o desligado da rede el\u00e9trica<\/strong> durante a fia\u00e7\u00e3o. Se a central tiver contactos secos (dry contacts<\/em>), liga os rel\u00e9s a\u00ed; caso contr\u00e1rio, usa uma sa\u00edda opto-isolada dimensionada para a tens\u00e3o de comando.<\/p>\r\n<\/div>\n\n\n\n

        Mapeamento dos GPIO<\/h2>\n\n\n\n

        Todos os pinos est\u00e3o fixados no YAML, com coment\u00e1rios que documentam a fun\u00e7\u00e3o de cada um. \u00c9 este o mapa completo:<\/p>\n\n\n\n

        Sinal<\/th>GPIO<\/th>Dire\u00e7\u00e3o<\/th>Fun\u00e7\u00e3o<\/th><\/tr><\/thead>
        Step<\/strong> (_completo<\/code>)<\/td>GPIO5<\/td>Sa\u00edda \u2192 rel\u00e9<\/td>Pulso de 1 s: abre ou fecha o port\u00e3o<\/td><\/tr>
        Parcial<\/strong> (_parcial<\/code>)<\/td>GPIO4<\/td>Sa\u00edda \u2192 rel\u00e9<\/td>Pulso de 1 s: abertura pedonal<\/td><\/tr>
        Luz Exterior<\/strong><\/td>GPIO16<\/td>Sa\u00edda \u2192 rel\u00e9<\/td>Interruptor liga\/desliga da ilumina\u00e7\u00e3o<\/td><\/tr>
        Port\u00e3o Fechado<\/strong><\/td>GPIO14<\/td>Entrada<\/td>Fim de curso de fecho (closed_endstop<\/code>)<\/td><\/tr>
        Port\u00e3o 1\/4 Aberto<\/strong><\/td>GPIO12<\/td>Entrada<\/td>Posi\u00e7\u00e3o interm\u00e9dia (open_midle<\/code>)<\/td><\/tr>
        Port\u00e3o Aberto<\/strong><\/td>GPIO13<\/td>Entrada<\/td>Fim de curso de abertura (open_endstop<\/code>)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

        Duas prote\u00e7\u00f5es merecem destaque. A primeira \u00e9 o interlock<\/strong>: o YAML define um grupo (interlock: &interlock_group [_parcial, _completo]<\/code>) que impede que os dois rel\u00e9s de movimento estejam ativos ao mesmo tempo \u2014 imposs\u00edvel pedir \u00ababrir\u00bb e \u00abfechar\u00bb em simult\u00e2neo. A segunda \u00e9 o modo moment\u00e2neo<\/strong>: cada rel\u00e9 de movimento desliga-se sozinho ao fim de 1 segundo, tal como um dedo a carregar no bot\u00e3o do telemando.<\/p>\n\n\n\n

        \r\n\tOK<\/span>\r\n\t

        Os tr\u00eas finais de curso usam delayed_on: 1000ms<\/code> e delayed_off: 1000ms<\/code>. Sem este filtro, a vibra\u00e7\u00e3o do port\u00e3o em movimento faria o estado oscilar e o cover<\/em> saltaria entre \u00aba abrir\u00bb e \u00aba fechar\u00bb. Com o filtro, s\u00f3 uma posi\u00e7\u00e3o confirmada durante um segundo completa \u00e9 publicada.<\/p>\r\n<\/div>\n\n\n\n

        O YAML, bloco a bloco<\/h2>\n\n\n\n

        O ficheiro portao.yaml<\/code> tem uma estrutura limpa e comentada. Estes s\u00e3o os excertos que interessam, do rel\u00e9 ao cover<\/em>:<\/p>\n\n\n\n

        Rel\u00e9s moment\u00e2neos com interlock<\/h3>\n\n\n
        switch<\/span>:\n  - platform: gpio\n    pin<\/span>: GPIO4\n    id<\/span>: _parcial\n    name<\/span>: \"Parcial\"<\/span>\n    icon<\/span>: \"mdi:gate\"<\/span>\n    on_turn_on<\/span>:\n      - delay: 1000<\/span>ms\n      - switch<\/span>.turn_off: _parcial\n    interlock<\/span>: &interlock_group [_parcial, _completo]\n\n  - platform: gpio\n    pin<\/span>: GPIO5\n    id<\/span>: _completo\n    name<\/span>: \"Step\"<\/span>\n    icon<\/span>: \"mdi:gate\"<\/span>\n    on_turn_on<\/span>:\n      - delay: 1000<\/span>ms\n      - switch<\/span>.turn_off: _completo\n    interlock<\/span>: *interlock_group<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
        Fim de curso que alimenta o estado do cover<\/h3>\n\n\n\n
        Cada sensor publica diretamente no cover<\/em> template: quando o port\u00e3o deixa de estar fechado, o estado passa a OPENING<\/code>; quando encosta no fim de curso de aberto, fica IDLE<\/code>. \u00c9 assim que o Home Assistant sabe sempre onde o port\u00e3o est\u00e1 \u2014 mesmo depois de um rein\u00edcio, porque a lambda<\/em> do cover<\/code> l\u00ea o sensor f\u00edsico:<\/p>\n\n\n
        binary_sensor:\n  - platform: gpio\n    pin<\/span>: { number<\/span>: GPIO14, mode<\/span>: INPUT, inverted<\/span>: true<\/span> }\n    filters<\/span>:\n      - delayed_on: 1000<\/span>ms\n      - delayed_off: 1000<\/span>ms\n    name<\/span>: \"Port\u00e3o Fechado\"<\/span>\n    id<\/span>: closed_endstop\n    on_press<\/span>:\n      - cover.template.publish:\n          id: door_position_sensor\n          current_operation<\/span>: IDLE\n          state<\/span>: 'CLOSED'<\/span>\n    on_release<\/span>:\n      - cover.template.publish:\n          id: door_position_sensor\n          current_operation<\/span>: OPENING\n          state<\/span>: \"OPEN\"<\/span>\n\ncover<\/span>:\n  - platform: template\n    name<\/span>: \"Port\u00e3o\"<\/span>\n    id<\/span>: door_position_sensor\n    device_class<\/span>: gate\n    open_action<\/span>:\n      then:\n        - switch<\/span>.turn_on: _completo\n    close_action<\/span>:\n      then:\n        - switch<\/span>.turn_on: _completo\n    lambda<\/span>: |-\n      if<\/span> (id(closed_endstop).state) {\n        return<\/span> COVER_CLOSED;\n      } else<\/span> {\n        return<\/span> COVER_OPEN;\n      }<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
        \r\n\ti<\/span>\r\n\t
        Porque \u00e9 que abrir e fechar s\u00e3o iguais?<\/strong> Num port\u00e3o comum, um pulso no mesmo bot\u00e3o alterna entre abrir e fechar. O cover<\/code> do Home Assistant manda open<\/em> quando queres abrir e close<\/em> quando queres fechar \u2014 ambos acabam no mesmo rel\u00e9 _completo<\/code>, e o pr\u00f3prio port\u00e3o decide o sentido com base no estado atual dele.<\/p>\r\n<\/div>\n\n\n\n
        Rede, gest\u00e3o e atualiza\u00e7\u00f5es<\/h2>\n\n\n\n
        A parte de rede \u00e9 onde este projeto se afasta do t\u00edpico smart device<\/em>: nada depende de um servidor de fabricante. A configura\u00e7\u00e3o garante:<\/p>\n\n\n\n
          \n
        • IP est\u00e1tico<\/strong> \u2014 o dispositivo vive sempre em 192.168.x.xxx<\/code>, com gateway<\/em> e DNS em 192.168.x.xxx<\/code>. Nada de reservas DHCP que mudam o endere\u00e7o e quebram automa\u00e7\u00f5es.<\/li>\n\n\n\n
        • Tr\u00eas redes Wi-Fi<\/strong> \u2014 SF24A<\/code>, SF24B<\/code> e SF24C<\/code> com as mesmas defini\u00e7\u00f5es est\u00e1ticas: se um dos pontos de acesso cair, o ESPHome passa ao seguinte.<\/li>\n\n\n\n
        • Access Point de emerg\u00eancia<\/strong> \u2014 com ap: {}<\/code> e captive_portal<\/code>, se nenhuma rede estiver dispon\u00edvel o dispositivo abre o seu pr\u00f3prio Wi-Fi e permite reconfigurar as credenciais pelo telem\u00f3vel.<\/li>\n\n\n\n
        • Improv Serial<\/strong> \u2014 provisionamento de Wi-Fi pela porta s\u00e9rie, \u00fatil na primeira configura\u00e7\u00e3o ou em bancada.<\/li>\n\n\n\n
        • OTA<\/strong> \u2014 atualiza\u00e7\u00f5es de firmware sem tocar no cabo, a partir do ESPHome no Home Assistant (ou do VS Code).<\/li>\n\n\n\n
        • Web Server<\/strong> \u2014 interface local para consultar estado e logs sem abrir o Home Assistant.<\/li>\n\n\n\n
        • API nativo<\/strong> \u2014 liga\u00e7\u00e3o direta ao Home Assistant, sem MQTT obrigat\u00f3rio.<\/li>\n<\/ul>\n\n\n
          wifi<\/span>:\n  ap<\/span>: {}\n  networks<\/span>:\n    -<\/span> ssid<\/span>: SF24A<\/span>\n      password<\/span>: \"\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\"\n      manual_ip<\/span>:\n        static_ip<\/span>: 192.168<\/span>.1<\/span>.227<\/span>\n        gateway<\/span>: 192.168<\/span>.1<\/span>.254<\/span>\n        subnet<\/span>: 255.255<\/span>.255<\/span>.0<\/span>\n        dns1<\/span>: 192.168<\/span>.1<\/span>.254<\/span>\n\ncaptive_portal<\/span>:<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
          \r\n\t!<\/span>\r\n\t
          Antes de publicar o YAML:<\/strong> as palavras-passe do Wi-Fi ficam em texto no ficheiro \u2014 mant\u00e9m o portao.yaml<\/code> fora de reposit\u00f3rios p\u00fablicos. Recomenda-se ainda definir api: encryption_key<\/code> para cifrar a liga\u00e7\u00e3o ao Home Assistant e ota: password<\/code> para proteger as atualiza\u00e7\u00f5es. Com IP est\u00e1tico, reserva tamb\u00e9m o endere\u00e7o no router para n\u00e3o haver conflitos.<\/p>\r\n<\/div>\n\n\n\n
          Instala\u00e7\u00e3o passo a passo<\/h2>\n\n\n\n
          Do ficheiro em branco ao port\u00e3o control\u00e1vel pelo telem\u00f3vel, em seis passos:<\/p>\n\n\n\n
            \n
          1. Liga a fia\u00e7\u00e3o em bancada.<\/strong> Monta ESP8266 + m\u00f3dulo rel\u00e9 + os tr\u00eas finais de curso numa protoboard e testa tudo antes de ir \u00e0 garagem. Confirma que o interlock impede os dois rel\u00e9s de fechar ao mesmo tempo.<\/li>\n\n\n\n
          2. Grava o firmware.<\/strong> Importa portao.yaml<\/code> no ESPHome (Home Assistant \u2192 ESPHome \u2192 Add Device), corrige as credenciais Wi-Fi e envia via OTA ou USB.<\/li>\n\n\n\n
          3. Adiciona ao Home Assistant.<\/strong> O dispositivo aparece em Dispositivos & Servi\u00e7os<\/em>; aceita a liga\u00e7\u00e3o API e as entidades Port\u00e3o<\/em>, Luz Exterior<\/em> e os diagn\u00f3sticos ficam dispon\u00edveis.<\/li>\n\n\n\n
          4. Instala na central do port\u00e3o.<\/strong> Liga os rel\u00e9s aos contactos do comando original e os finais de curso aos pontos de dete\u00e7\u00e3o. Alimenta o conjunto com 5\u00a0V e fixa a caixa junto \u00e0 central.<\/li>\n\n\n\n
          5. Calibra os finais de curso.<\/strong> Usa o logger<\/em> do ESPHome para verificar CLOSED<\/code>\/OPEN<\/code> e ajusta a posi\u00e7\u00e3o dos sensores at\u00e9 os tr\u00eas estados baterem certo com a posi\u00e7\u00e3o real do port\u00e3o.<\/li>\n\n\n\n
          6. Monta o dashboard e as automa\u00e7\u00f5es.<\/strong> Adiciona o cover<\/em> ao painel, a luz exterior a um tile<\/em> e cria as automa\u00e7\u00f5es de fecho autom\u00e1tico (ver sec\u00e7\u00e3o seguinte).<\/li>\n<\/ol>\n\n\n\n
            No Home Assistant<\/h2>\n\n\n\n
            Depois de pareado, o dispositivo cria um conjunto de entidades pronto a usar. \u00c9 no dashboard que o projeto ganha vida:<\/p>\n\n\n\n
            \r\n\r\n\t
            \r\n\t\t01<\/span>\r\n\t\t
            Cart\u00e3o do port\u00e3o<\/h3>\r\n\t\t
            O cover<\/em> Port\u00e3o<\/strong> mostra estado e a\u00e7\u00e3o num s\u00f3 s\u00edtio: toca para abrir, toca e segura para parar, desliza para pedir abertura parcial. Funciona no telem\u00f3vel, no tablet de parede e no browser.<\/p>\r\n\t<\/div>\r\n\r\n\t
            \r\n\t\t02<\/span>\r\n\t\t
            Luz exterior<\/h3>\r\n\t\t
            O interruptor Luz Exterior<\/strong> (mdi:car-light-dimmed<\/code>) controla a ilumina\u00e7\u00e3o da garagem e pode ser agrupado com o port\u00e3o num \u00fanico cart\u00e3o ou num tile<\/em> do dashboard.<\/p>\r\n\t<\/div>\r\n\r\n\t
            \r\n\t\t03<\/span>\r\n\t\t
            Diagn\u00f3stico sempre vis\u00edvel<\/h3>\r\n\t\t
            Sinal Wi-Fi (a cada 10 s), uptime<\/em>, vers\u00e3o do ESPHome e SSID da rede \u2014 entidades que resolvem 90% dos problemas \u00e0 dist\u00e2ncia, sem ir \u00e0 garagem.<\/p>\r\n\t<\/div>\r\n\r\n<\/div>\n\n\n\n
            Automa\u00e7\u00f5es que valem a pena<\/h3>\n\n\n\n
            Com o port\u00e3o exposto como cover<\/em>, qualquer automa\u00e7\u00e3o \u00e9 poss\u00edvel. Estas tr\u00eas s\u00e3o as mais \u00fateis no dia a dia:<\/p>\n\n\n\n