Automação de Portão com ESPHome e Home Assistant

O ESPPortao transforma um portão de garagem convencional num dispositivo inteligente, sem trocar o motor nem o comando original: um ESP8266 a correr ESPHome simula os botões do controlo remoto por relé, lê três sensores de fim de curso e expõe o portão ao Home Assistant como uma entidade cover nativa. Abertura total, abertura pedonal, estado em tempo real e iluminação exterior — tudo local, sem nuvem e sem subscrições.

Visão geral do sistema

A ideia é simples: em vez de comprar um kit de automação fechado, usa-se o próprio comando do portão. O microcontrolador fecha os contactos dos botões abrir/fechar e parcial exatamente como faria o telemando, e três sensores de fim de curso dizem onde o portão está em cada momento. O resultado é um sistema híbrido — o portão continua a funcionar com o comando original, e o ESPHome acrescenta controlo remoto, automações e monitorização.

• 3Saídas relé: passo completo, parcial e luz
• 3Sensores de fim de curso com filtro anti-vibração
• 1 sPulso momentâneo com interlock entre relés
• 0Serviços externos ou dependência da nuvem

A entidade central é um cover template com device_class: gate. Isto significa que no Home Assistant o portão aparece com o ícone, 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ção como qualquer portão inteligente de fabricante.

Hardware e esquema de ligação

Não há nada exótico na lista de materiais. Tudo cabe numa pequena caixa de embutir junto à central do portão, alimentado por uma fonte de 5 V:

• Placa ESP8266 — o YAML declara board: esp01_1m; na prática, use uma placa com os pins expostos (NodeMCU ou Wemos D1 mini).
• Módulo relé de 3 canais — opto-isolado, com saída NO/NC, para simular os botões do comando e comandar a luz exterior.
• 3 botões fim de curso (normalmente abertos) — um no fim de curso de fechado, um na posição intermédia e um no fim de curso de aberto.
• Fonte de 5 V DC — USB ou regulador, consoante o sítio de instalação.
• Caixa de embutir e cabo de ligação ao comando existente.

Mapeamento dos GPIO

Todos os pinos estão fixados no YAML, com comentários que documentam a função de cada um. É este o mapa completo:

Sinal	GPIO	Direção	Função
Step (_completo)	GPIO5	Saída → relé	Pulso de 1 s: abre ou fecha o portão
Parcial (_parcial)	GPIO4	Saída → relé	Pulso de 1 s: abertura pedonal
Luz Exterior	GPIO16	Saída → relé	Interruptor liga/desliga da iluminação
Portão Fechado	GPIO14	Entrada	Fim de curso de fecho (closed_endstop)
Portão 1/4 Aberto	GPIO12	Entrada	Posição intermédia (open_midle)
Portão Aberto	GPIO13	Entrada	Fim de curso de abertura (open_endstop)

Duas proteções merecem destaque. A primeira é o interlock: o YAML define um grupo (interlock: &interlock_group [_parcial, _completo]) que impede que os dois relés de movimento estejam ativos ao mesmo tempo — impossível pedir «abrir» e «fechar» em simultâneo. A segunda é o modo momentâneo: cada relé de movimento desliga-se sozinho ao fim de 1 segundo, tal como um dedo a carregar no botão do telemando.

O YAML, bloco a bloco

O ficheiro portao.yaml tem uma estrutura limpa e comentada. Estes são os excertos que interessam, do relé ao cover:

Relés momentâneos com interlock

switch:
  - platform: gpio
    pin: GPIO4
    id: _parcial
    name: "Parcial"
    icon: "mdi:gate"
    on_turn_on:
      - delay: 1000ms
      - switch.turn_off: _parcial
    interlock: &interlock_group [_parcial, _completo]

  - platform: gpio
    pin: GPIO5
    id: _completo
    name: "Step"
    icon: "mdi:gate"
    on_turn_on:
      - delay: 1000ms
      - switch.turn_off: _completo
    interlock: *interlock_groupCode language: JavaScript (javascript)

Fim de curso que alimenta o estado do cover

Cada sensor publica diretamente no cover template: quando o portão deixa de estar fechado, o estado passa a OPENING; quando encosta no fim de curso de aberto, fica IDLE. É assim que o Home Assistant sabe sempre onde o portão está — mesmo depois de um reinício, porque a lambda do cover lê o sensor físico:

binary_sensor:
  - platform: gpio
    pin: { number: GPIO14, mode: INPUT, inverted: true }
    filters:
      - delayed_on: 1000ms
      - delayed_off: 1000ms
    name: "Portão Fechado"
    id: closed_endstop
    on_press:
      - cover.template.publish:
          id: door_position_sensor
          current_operation: IDLE
          state: 'CLOSED'
    on_release:
      - cover.template.publish:
          id: door_position_sensor
          current_operation: OPENING
          state: "OPEN"

cover:
  - platform: template
    name: "Portão"
    id: door_position_sensor
    device_class: gate
    open_action:
      then:
        - switch.turn_on: _completo
    close_action:
      then:
        - switch.turn_on: _completo
    lambda: |-
      if (id(closed_endstop).state) {
        return COVER_CLOSED;
      } else {
        return COVER_OPEN;
      }Code language: JavaScript (javascript)

Rede, gestão e atualizações

A parte de rede é onde este projeto se afasta do típico smart device: nada depende de um servidor de fabricante. A configuração garante:

• IP estático — o dispositivo vive sempre em 192.168.x.xxx, com gateway e DNS em 192.168.x.xxx. Nada de reservas DHCP que mudam o endereço e quebram automações.
• Três redes Wi-Fi — SF24A, SF24B e SF24C com as mesmas definições estáticas: se um dos pontos de acesso cair, o ESPHome passa ao seguinte.
• Access Point de emergência — com ap: {} e captive_portal, se nenhuma rede estiver disponível o dispositivo abre o seu próprio Wi-Fi e permite reconfigurar as credenciais pelo telemóvel.
• Improv Serial — provisionamento de Wi-Fi pela porta série, útil na primeira configuração ou em bancada.
• OTA — atualizações de firmware sem tocar no cabo, a partir do ESPHome no Home Assistant (ou do VS Code).
• Web Server — interface local para consultar estado e logs sem abrir o Home Assistant.
• API nativo — ligação direta ao Home Assistant, sem MQTT obrigatório.

wifi:
  ap: {}
  networks:
    - ssid: SF24A
      password: "••••••••"
      manual_ip:
        static_ip: 192.168.1.227
        gateway: 192.168.1.254
        subnet: 255.255.255.0
        dns1: 192.168.1.254

captive_portal:Code language: CSS (css)

Instalação passo a passo

Do ficheiro em branco ao portão controlável pelo telemóvel, em seis passos:

1. Liga a fiação em bancada. Monta ESP8266 + módulo relé + os três finais de curso numa protoboard e testa tudo antes de ir à garagem. Confirma que o interlock impede os dois relés de fechar ao mesmo tempo.
2. Grava o firmware. Importa portao.yaml no ESPHome (Home Assistant → ESPHome → Add Device), corrige as credenciais Wi-Fi e envia via OTA ou USB.
3. Adiciona ao Home Assistant. O dispositivo aparece em Dispositivos & Serviços; aceita a ligação API e as entidades Portão, Luz Exterior e os diagnósticos ficam disponíveis.
4. Instala na central do portão. Liga os relés aos contactos do comando original e os finais de curso aos pontos de deteção. Alimenta o conjunto com 5 V e fixa a caixa junto à central.
5. Calibra os finais de curso. Usa o logger do ESPHome para verificar CLOSED/OPEN e ajusta a posição dos sensores até os três estados baterem certo com a posição real do portão.
6. Monta o dashboard e as automações. Adiciona o cover ao painel, a luz exterior a um tile e cria as automações de fecho automático (ver secção seguinte).

No Home Assistant

Depois de pareado, o dispositivo cria um conjunto de entidades pronto a usar. É no dashboard que o projeto ganha vida:

Automações que valem a pena

Com o portão exposto como cover, qualquer automação é possível. Estas três são as mais úteis no dia a dia:

• Fecho automático — se o portão ficar aberto mais de 10 minutos sem movimento, fecha-o e envia uma notificação.
• Luz ao abrir — ao detetar current_operation: opening à noite, liga a luz exterior; dois minutos depois de IDLE, desliga.
• Modo saída de casa — um scene que fecha o portão, apaga a luz e desliga a saída quando sares de casa.

alias: Portão - fecho automático
trigger:
  - platform: state
    entity_id: cover.portao
    to: "open"
    for:
      minutes: 10
condition:
  - condition: state
    entity_id: cover.portao
    state: "open"
action:
  - service: cover.close_cover
    target:
      entity_id: cover.portao
  - service: notify.mobile_app
    data:
      message: "Portão da garagem fechado automaticamente."Code language: CSS (css)

Diagnóstico e boas práticas

Quando algo falha, os quatro pontos abaixo resolvem quase sempre o problema:

1. O portão não responde no HA. Vê o sinal Wi-Fi e o uptime: se o dispositivo reiniciou de forma repetida, verifica a alimentação de 5 V (relés a puxar corrente demais é a causa clássica — usa uma fonte com margem).
2. Estado errado após um reinício. O cover confia no fim de curso closed_endstop. Se o portão está fechado e o sensor não está ativado, o HA mostrará aberto; recalibra a posição do fim de curso.
3. Estados a saltitar. Aumenta os filtros delayed_on/off (por exemplo para 2000 ms) — indica vibração do portão ou contacto do fim de curso a falhar.
4. Perdeu a ligação Wi-Fi. Liga ao AP de emergência com o telemóvel, reentra as credenciais e o dispositivo volta a ligar-se às redes configuradas, mantendo o IP estático.

Conclusão

O ESPPortao prova que não é preciso um kit caro nem uma ligação à nuvem para ter um portão inteligente. Com uma placa de poucos euros, três relés e três finais de curso, obtém-se o que os sistemas comerciais oferecem — estados fiáveis, controlo total e integração nativa — e ainda se mantém o comando original intacto como alternativa física.

É um projeto replicável: copia o portao.yaml, ajusta os GPIO às tuas ligações, calibra os finais de curso e tens o portão no dashboard ao fim de uma tarde. Tudo local, tudo teu.