Primeiros passos com ESPHome

O que é o ESPHome

Você descreve o dispositivo num arquivo YAML: qual placa, quais sensores em quais pinos, como ele se conecta à sua rede. O ESPHome transforma essa descrição em firmware, compila e grava na placa. Depois, o Home Assistant conversa com o dispositivo pela API nativa do ESPHome, uma conexão direta na porta TCP 6053 que pode ser criptografada com uma chave de 32 bytes.

Para as partes mais comuns não há código para escrever. Quando você muda o YAML, instala de novo e o dispositivo passa a rodar o novo firmware.

Instalar o ESPHome

A ferramenta em que você trabalha se chama ESPHome Device Builder: um painel web que guarda seus arquivos YAML, compila os arquivos e instala o firmware. Escolha como rodá-lo:

• No Home Assistant. Vá em Configurações → Aplicativos → Instalar aplicativo (o Home Assistant agora chama de “aplicativos” os seus complementos), procure o ESPHome Device Builder e clique em Instalar, Iniciar e Abra a interface do usuário da Web. Se ele não aparecer, adicione o repositório https://github.com/esphome/home-assistant-addon pelo menu ⋮.
• Como app de desktop. A página de instalação oferece o ESPHome Device Builder para macOS (um .dmg), para Windows e para Linux (um .deb ou um AppImage). No Linux, se as portas seriais não aparecerem, adicione seu usuário ao grupo dialout.
• No Docker. O mesmo painel atende na porta 6052. Rode o contêiner com a rede do host (--net=host) para ele encontrar os dispositivos por mDNS; no Docker Desktop, publique a porta 6052.
• Pela linha de comando. pip install esphome (num ambiente virtual, se puder) e depois esphome run sala.yaml, que valida, compila, grava e mostra o log de uma vez.

Para a primeira gravação, você também pode usar o ESPHome Web, em web.esphome.io, que grava o firmware na placa direto do navegador. Ele precisa de Web Serial: Chrome, Edge e, segundo a documentação do ESP Web Tools, Firefox; não funciona no iOS.

Escolher a placa

Qualquer placa de desenvolvimento com ESP32 ou ESP8266 serve. Estas quatro são comuns, baratas e bem suportadas; o identificador da placa é o que vai no YAML.

Identificadores conferidos com esphome config no ESPHome 2026.10.2. Nosso comparativo ESP32 mostra as diferenças entre os chips.

Na dúvida, comece com um ESP32 DevKit: é o deste guia, e a maioria das respostas que você vai achar na internet pressupõe que você usa um.

Uma primeira configuração, linha por linha

No Device Builder, Create device abre um assistente que escreve quase tudo para você. Este é o arquivo completo de um dispositivo chamado sala, antes de qualquer sensor:

esphome:
  name: sala                   # nome do host: minúsculas, dígitos, hífens
  friendly_name: Sala          # o nome que o Home Assistant mostra

esp32:
  board: esp32dev              # a sua placa
  framework:
    type: esp-idf              # o padrão desde a 2026.1

logger:                        # log por USB e Wi-Fi

api:                           # a ligação com o Home Assistant
  encryption:
    key: !secret api_key

ota:
  - platform: esphome          # atualizações por Wi-Fi
    encryption:                # reaproveita a chave da API

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:                          # ponto de acesso reserva
    password: !secret ap_password

captive_portal:                # a página dele

• esphome: → name é o nome do host na sua rede, sala.local: até 31 caracteres, letras minúsculas, dígitos e hífens. friendly_name é o que o Home Assistant mostra.
• esp32: → board informa ao ESPHome o chip e o tamanho da flash. Desde o ESPHome 2026.1, o framework padrão no ESP32 é o ESP-IDF; declarar isso explicitamente deixa o arquivo mais claro. O Arduino continua suportado com type: arduino.
• logger: → o log por USB e pela rede, por padrão no nível DEBUG e a 115200 baud.
• api: → a API nativa que o Home Assistant usa, com a chave de criptografia. Sem chave, a conexão não é criptografada.
• ota: → as atualizações por Wi-Fi. Desde o ESPHome 2026.9, um encryption: vazio as criptografa com a chave da API.
• wifi: → a sua rede, lida do secrets.yaml. ap: liga um ponto de acesso reserva, com o nome do dispositivo, se ele não conseguir se conectar em 90 segundos.
• captive_portal: → uma página nesse ponto de acesso para digitar novos dados do Wi-Fi.

Os valores !secret vêm de um segundo arquivo, secrets.yaml, na mesma pasta:

wifi_ssid: "MyNetwork"
wifi_password: "MyWiFiPassword"
api_key: "…"                   # openssl rand -base64 32
ap_password: "…"

A chave da API são 32 bytes aleatórios em base64: o assistente cria uma, ou você pode gerá-la com o comando do comentário. Nunca publique o secrets.yaml.

Um primeiro sensor: BME280 por I²C

O BME280 mede temperatura, umidade e pressão e se comunica por I²C, então bastam dois fios de sinal. Num ESP32 DevKit, os pinos I²C que o ESPHome costuma usar são o GPIO21 para SDA e o GPIO22 para SCL.

Acrescente isto no fim do arquivo:

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true                   # lista os endereços encontrados

sensor:
  - platform: bme280_i2c
    address: 0x76              # ou 0x77, veja o log
    temperature:
      name: Temperatura
    pressure:
      name: Pressão
    humidity:
      name: Umidade
    update_interval: 60s

• i2c: → o barramento e os pinos dele. scan: true, o valor padrão, escreve no log os endereços que encontra.
• platform: bme280_i2c → o driver do BME280. O endereço padrão é 0x77; muitas placas baratas respondem em 0x76, como aqui. Nossa página sobre o endereço do BME280 explica como escolher entre os dois pelo pino SDO.
• Cada medida ganha um name, que vira uma entidade no Home Assistant. update_interval: 60s lê o sensor uma vez por minuto.

Prefere clicar? Nosso gerador monta um arquivo equivalente, já com este BME280, e cria as chaves para você. Ele coloca a chave da API no próprio arquivo, em vez de usar o secrets.yaml, e acrescenta sensores de sinal Wi-Fi e de tempo de atividade.Abrir o gerador ESPHome

Quer outro sensor? Nosso comparativo de sensores coloca os mais comuns lado a lado, do DHT22 aos SHT4x.

Gravar o firmware: primeiro por USB, depois por Wi-Fi

A primeira instalação precisa ser feita com um cabo USB. No Device Builder, clique em Install no cartão do dispositivo e escolha como:

• Plug into this computer grava pelo seu navegador. Usa Web Serial, que exige uma página segura: o painel aberto em HTTPS, ou em localhost, como no app de desktop.
• Plug into the computer running ESPHome Device Builder grava pela máquina que roda o painel, por exemplo o seu servidor do Home Assistant.
• Manual download e depois Factory format geram um arquivo .bin para gravar com o ESPHome Web: Connect, escolha a porta, Install.

Na linha de comando, esphome run sala.yaml pergunta qual porta serial usar. Se nenhuma porta aparecer:

• Teste outro cabo USB: os que só carregam não têm os fios de dados.
• Instale o driver do chip USB-serial da placa, normalmente um CH34x ou um CP2102.
• Segure o botão BOOT da placa enquanto conecta o cabo e depois solte: assim o chip inicia em modo de download.

Depois que o dispositivo entra no seu Wi-Fi, cada Install seguinte oferece Wirelessly, e o esphome run envia o firmware pela rede.

Adicionar ao Home Assistant

Se o mDNS funciona na sua rede, o Home Assistant encontra o dispositivo novo sozinho. Vá em Configurações → Dispositivos & Serviços: na seção Descoberto vai aparecer um cartão do ESPHome com o nome dele. Clique em Configurar, digite a chave de criptografia quando for pedida (se o Device Builder roda como app do Home Assistant, ela muitas vezes já vem preenchida) e escolha uma área.

Se nada for descoberto, clique em Adicionar integração, escolha ESPHome e digite sala.local ou o endereço IP do dispositivo. As três medidas do sensor aparecem como entidades, prontas para o painel.

Entre as opções da integração está a que permite ao dispositivo executar ações do Home Assistant, desligada por padrão. Ative-a só em dispositivos de confiança, e só se o seu YAML precisar dela.

Ler o log

É no log que qualquer problema aparece primeiro. No Device Builder, Logs mostra o log por USB se a placa estiver conectada e, se não, pela rede; na linha de comando, use esphome logs sala.yaml. Quando você se conecta, o dispositivo imprime a configuração dele, incluindo a varredura I²C:

[C][i2c:113]: Results from bus scan:
[C][i2c:119]: Found device at address 0x76

O número depois de i2c indica a linha do código-fonte do ESPHome, então muda de uma versão para outra. “Found no devices” indica um problema de fiação ou de alimentação, não de YAML. Uma leitura por minuto, nas linhas [D], quer dizer que o sensor funciona.

Erros comuns

Os pinos de strapping decidem como o chip inicia: um sensor ou LED que segure um deles em nível alto ou baixo pode impedir o boot.

Segurança

• Criptografia da API. Sempre defina uma chave: sem ela, a conexão não é criptografada nem exige chave, e qualquer aparelho da sua rede pode se conectar.
• Atualizações criptografadas. Com encryption: em ota: (ESPHome 2026.9 em diante), o dispositivo só aceita firmware criptografado com a sua chave. Guias mais antigos usam password:; o ESPHome agora avisa que isso gasta flash e RAM e recomenda a criptografia, e as duas coisas não podem ser combinadas.
• Uma senha no ponto de acesso reserva. A página dele deixa quem se conectar mudar o Wi-Fi e enviar um firmware.
• Guarde o secrets.yaml só para você, e faça backup: sem a chave, não dá para atualizar o dispositivo por Wi-Fi.

Manter tudo atualizado

O ESPHome lança uma versão nova todo mês. Atualizar o Device Builder (ou pip install --upgrade esphome) não muda os seus dispositivos: cada um continua com o firmware gravado nele até você clicar em Install de novo. Leia antes as mudanças incompatíveis nas notas da versão e atualize um dispositivo antes dos outros.

Na bateria: deep sleep

Um sensor que só precisa enviar leituras a cada poucos minutos pode dormir nos intervalos com o componente deep_sleep:, ajustado por run_duration e sleep_duration. Enquanto dorme, o Home Assistant mostra o dispositivo como indisponível, e ele só aceita atualização quando está acordado. A escolha de placa, bateria e regulador, com os consumos reais, está no nosso guia para alimentar um ESP32 com bateria.