Home Assistant DIY: como fazer projetos ESPHome que não quebram

Quando o Home Assistant deixou de ser só um hub para lâmpadas Philips Hue e passou a rodar automações sérias com ESPHome, eu percebi que o jogo mudou. Segundo o Sapo.pt, na segunda parte desta série sobre projetos DIY, a comunidade já monta desde sensores ultrassónicos para caves até fechaduras que rodam puxadores sem alterar a porta. O que me interessa — e o que vou destrinchar aqui — é o que está por baixo desses projetos, porque a diferença entre um gadget que vive no YouTube e um que sobrevive em produção está toda nos detalhes técnicos que a fonte original não cobre.

Sensor de nível de água com ESP32-C3 + HC-SR04 — o que ninguém te conta

A ideia original do Sapo.pt é direta: poço de drenagem propenso a inundação, sensor ultrassónico fixado no topo, leitura contínua enviada para o Home Assistant via ESPHome. Funciona no papel, mas eu não implementaria exatamente assim em produção.

O HC-SR04 tradicional — aquele módulo azul de dois transdutores cilíndricos — sofre com reflexos múltiplos quando há água parada logo abaixo, porque a superfície plana age como um espelho acústico. Eu já medi leituras oscilando 5cm em sequência por causa disso. Em produção eu trocaria pelo JSN-SR04T, versão selada com transdutor separado por cabo, mais estável em ambientes húmidos e com melhor ângulo de leitura.

Sobre o ESP32-C3: é a minha escolha para projetos novos. Tem Wi-Fi e Bluetooth 5, custa metade de um ESP32 clássico e é RISC-V, o que tem implicações interessantes quando você precisa rodar código de borda com consumo controlado. O GPIO é mais limitado que o ESP32 tradicional, mas para um sensor ultrassónico basta — você só precisa de dois pinos livres.

O ponto crítico é o tempo de echo. O HC-SR04 mede distâncias teóricas de 2cm a 400cm, mas a precisão cai em distâncias curtas e quando a temperatura varia muito — o som viaja diferente no frio e no quente. Para um poço de drenagem típico de 1,5m de profundidade, o range é confortável. Mas configure sempre um filtro de média móvel no ESPHome: eu uso sliding_window com window_size: 5 e send_every: 3. Isso elimina 90% das leituras espúrias que disparam alarmes falsos às 3h da manhã.

Fechadura DIY que gira o puxador existente — a parte mecânica importa

Esse é o projeto mais engenhoso da lista. Em casas arrendadas você não pode trocar a fechadura, mas pode montar um motor — normalmente um NEMA 17 ou um servo MG996R — acoplado a uma engrenagem impressa em 3D que encaixa por trás do puxador. O motor gira no sentido horário, tranca; no sentido anti-horário, destranca. Sem furar nada, sem alterar a porta, sem perder o depósito caução.

Na minha experiência com projetos parecidos, o cuidado aqui é 70% mecânico e 30% de software. Você precisa de três coisas que a maioria dos tutoriais ignora:

Motor com torque suficiente. O MG996R aguenta cerca de 11kg/cm, suficiente para a maioria dos puxadores cilíndricos. Para puxadores maiores, vá de NEMA 17 com driver A4988.
Limit switches para detectar fim de curso. Sem isso você vai queimar o motor quando a fechadura travar no batente. Dois micro-switches — um para “trancado”, outro para “destrancado” — custam R$5 e salvam o motor.
Fonte de alimentação dedicada. Jamais alimente o motor pela USB do ESP. Os picos de corrente durante o acionamento reiniciam o microcontrolador no meio da operação. Use uma fonte de 5V 2A separada, com GND comum.

Sobre a integração com o Home Assistant: pode ser via MQTT ou pela API nativa do ESPHome. Eu prefiro MQTT porque facilita a integração com sistemas legados no futuro — você não fica preso ao ecossistema. Publica um tópico lock/state e escuta lock/command, simples assim.

Os outros projetos da série — o padrão subjacente

O Sapo.pt cita ainda quatro categorias que valem a investigação: sistemas de segurança com câmaras e sensores PIR, dashboards em ecrãs tácteis com Fire Tablet ou tablets Android dedicados, automação de jardins com válvulas de irrigação controladas, e monitorização de aquários com sensores de temperatura e nível. A maioria segue o mesmo padrão arquitetural: ESP ou Raspberry Pi + ESPHome + integração nativa com o HA.

O que diferencia projetos amadores de projetos profissionais é a camada de automação. Um sensor de inundação que só aparece no dashboard é inútil — você precisa de uma automação que feche a válvula principal, mande notificação no Telegram e acenda uma luz vermelha de alerta quando o nível ultrapassa o threshold. Um dashboard bonito sem lógica por trás é só decoração.

Na Prática: do zero ao sensor funcional

Antes de colar o código, o caminho crítico é este:

Conectar o pino trig do HC-SR04 ao GPIO5 e o echo ao GPIO4 do ESP32-C3.
Alimentar o sensor com 5V do pino VIN do ESP (apenas o sensor — motores vão em fonte separada).
Instalar o add-on ESPHome no Home Assistant via Add-on Store.
Criar o arquivo de configuração abaixo e gravar no ESP via USB.
Adicionar a integração nativa no HA — o dispositivo aparece sozinho na rede mDNS.
Criar a automação que age sobre o estado do sensor.

Configuração ESPHome funcional para um sensor HC-SR04 num ESP32-C3:

esphome:
  name: sensor-cave
  friendly_name: "Sensor Cave"
  platform: ESP32
  board: esp32-c3-devkitm-1

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_key

logger:
  level: INFO

sensor:
  - platform: ultrasonic
    trigger_pin: GPIO5
    echo_pin: GPIO4
    name: "Distancia Poco"
    update_interval: 30s
    unit_of_measurement: "cm"
    accuracy_decimals: 1
    filters:
      - sliding_window_moving_average:
          window_size: 5
          send_every: 3
      - lambda: |-
          return 150.0 - x;  # converte distância em nível de água

binary_sensor:
  - platform: template
    name: "Alerta Inundacao"
    lambda: |-
      if (id(distancia_poco).state < 30) return true;
      return false;

No Home Assistant, a automação que transforma o sensor em algo realmente útil:

automation:
  - alias: "Alerta de Inundacao na Cave"
    trigger:
      - platform: state
        entity_id: binary_sensor.alerta_inundacao
        to: 'on'
        for: "00:00:30"
    action:
      - service: notify.telegram
        data:
          message: "ALERTA: agua a menos de 30cm do topo do poco!"
      - service: switch.turn_off
        target:
          entity_id: switch.bomba_drenagem
      - service: light.turn_on
        target:
          entity_id: light.led_alerta_cave
        data:
          color_name: red
          brightness: 255

Repare no for: "00:00:30" — sem isso, uma leitura espúria de 2 segundos já dispara a cascata inteira. É exatamente esse tipo de detalhe que separa código de hobby de código de produção.

Erros Comuns — o que evitar

Eu já queimei motores, reiniciei ESPs em loop e mandei alertas falsos no meio da madrugada. Estes são os pontos onde vejo devs perdendo tempo precioso:

Alimentar o motor pelo mesmo regulador do ESP. Picos de corrente reiniciam o microcontrolador no meio da operação e corrompem o estado interno. Use sempre uma fonte separada para cargas indutivas, com GND comum ao ESP.
Esquecer dos limit switches. Se o motor encontrar resistência mecânica e continuar forçando contra o batente, você queima o driver e potencialmente a fechadura. Fins de curso custam R$5 — não economize neles.
Confiar na primeira leitura do sensor ultrassónico. O filtro de média móvel não é cosmético, é funcional. Sem ele, você vai receber notificações às 3h da manhã por causa de uma leitura espúria.
Não tratar o caso "sensor offline". Crie uma automação que alerta quando o sensor não reporta há mais de 10 minutos. Sensores offline são mais perigosos que sensores com valores errados — porque a ausência de dado é silenciosa.
Hardcodar credenciais Wi-Fi no YAML. Use !secret apontando para um arquivo secrets.yaml que vai pro .gitignore. Parece óbvio, mas 90% dos repositórios no GitHub expõem SSID e password em commits públicos.
Não versionar a configuração. O YAML do ESPHome e do Home Assistant é código. Coloque num repositório Git, com branches por ambiente. Quando a sua casa parar de funcionar do nada, o histórico de mudanças vai salvar horas de debug.

FAQ — Perguntas Frequentes

ESPHome ou Tasmota para projetos DIY com Home Assistant?

Para quem programa, ESPHome é a escolha óbvia: YAML declarativo, integração nativa com Home Assistant via API local, código versionado em Git. Tasmota é mais maduro e tem mais templates prontos para dispositivos comerciais, mas a customização via Rules é limitada e vira spaghetti em projetos não-triviais.

Matter substitui o Home Assistant?

Não. Matter resolve a interoperabilidade entre dispositivos — um sensor de uma marca conversa com um hub de outra. Mas não entrega a camada de automação avançada que o Home Assistant oferece. Os dois se complementam: você usa dispositivos Matter compatíveis e centraliza toda a lógica no HA.

Posso usar Raspberry Pi Pico W em vez do ESP32?

Pode, mas perde a compatibilidade nativa com ESPHome. Vai ter que escrever firmware próprio em MicroPython ou C, e a integração com Home Assistant fica via MQTT — mais código, menos conveniência. Pico W vale a pena quando você precisa de I/O específico que o ESP não tem, ou quer rodar lógica mais pesada localmente.

Quanto custa montar um setup básico como esses projetos?

ESP32-C3: ~R$40. HC-SR04: ~R$10. JSN-SR04T (versão impermeável, recomendada): ~R$45. Fonte 5V 2A: ~R$20. Cabo e caixa impressa em 3D: ~R$30. Total entre R$100 e R$150 dependendo do sensor escolhido — bem mais barato que qualquer solução comercial com o mesmo nível de integração.

Esses projetos funcionam com Alexa ou Google Home em paralelo?

Sim, via Nabu Casa (serviço pago oficial do Home Assistant) ou via emuladores locais como o HA Bridge. Mas honestamente, perde parte da graça — o valor do HA é justamente a automação local sem depender de cloud externa. Eu mantenho o Nabu Casa ativo só para acesso remoto via app, mas toda a lógica crítica roda 100% offline.

Gostou? Me segue no GitHub e deixa um comentário se tiver dúvida ou quiser aprofundar algum ponto.