Skip to main content

​
ESPHome

A integração ESPHome se conecta diretamente à API nativa de qualquer firmware ESPHome (porta TCP 6053), sem precisar passar por um broker MQTT externo. Funciona tanto com dispositivos do próprio usuário quanto com módulos ESP de terceiros já em produção. Diferente do Flexhome (que é o nosso firmware customizado adotado por QR/MAC), esta integração fala o protocolo aberto do ESPHome — todo dispositivo flashado com esphome compile é compatível.

​
Plataformas suportadas no v1

  • switch (turn_on / turn_off / toggle)
  • binary_sensor (estado on/off)
  • button (press)
  • cover (open / close / stop / set_position)
  • lock (lock / unlock / open)
  • sensor (numérico — uptime, RSSI, temperatura, etc., com unit_of_measurement)
  • text_sensor (string — versão do firmware, IP, status custom, etc.)
Plataformas que ainda não são suportadas: light, climate, fan, number, select, media_player, valve. Adicionar suporte é mecânico (mais um decoder no messages.ts + uma entrada no service-map.ts) — abra uma issue se precisar.

​
Pré-requisitos

  • O dispositivo precisa estar na mesma rede LAN do edge home do Portal.
  • A porta 6053/TCP precisa estar acessível (firmware ESPHome com api: habilitado, sem firewall bloqueando).
  • Suportamos os dois modos de autenticação:
    • Noise (recomendado) — api.encryption.key no YAML.
    • Senha legada — api.password no YAML (modo plaintext, sem criptografia em trânsito).

​
YAML mínimo no firmware

Para um dispositivo de teste com switch + binary_sensor: 
api:
  encryption:
    key: "BcMxxx...32B base64..."   # gere com `esphome wizard`

switch:
  - platform: gpio
    pin: GPIO2
    name: "Teste Switch"

binary_sensor:
  - platform: gpio
    pin: GPIO0
    name: "Teste Botão"

​
Configurar no Portal

1

Obtenha a chave de criptografia

Abra o YAML do firmware e copie o valor de api.encryption.key. Se o seu dispositivo usa apenas api.password, anote a senha.
2

Adicione a integração

Vá em Configurações → Integrações → Adicionar → ESPHome.
3

Preencha os dados

  • Host: IP ou hostname do dispositivo (ex.: 192.168.1.42 ou esphome-living.local)
  • Porta: 6053 (padrão; só altere se você mudou no firmware)
  • Chave de criptografia (Noise): cole o api.encryption.key
  • Senha (legada): deixe vazio se usa Noise; preencha apenas para firmwares com api.password
4

Aguarde o probe

O Portal abre uma conexão de teste, lê DeviceInfo e cria a config entry. Em alguns segundos, todas as entidades suportadas do dispositivo aparecem no dashboard.

​
Como funciona

  • Conexão persistente: o edge home mantém uma conexão TCP aberta com cada dispositivo. Atualizações de estado chegam em tempo real (subscribe states), sem polling.
  • Reconexão automática: se a conexão cair (queda de rede, reboot do dispositivo, etc.), o edge reconecta com backoff exponencial (1s → 2s → 5s → 10s → 30s, com jitter de ±20%).
  • Sync de entidades: a cada (re)conexão, o edge chama ListEntities e sincroniza com o registry do Portal. Adicionar/remover entidades no firmware reflete no Portal automaticamente após reflash + reconexão.
ESPHome reservou a porta 6053 para essa API. Não há necessidade de configurar um broker MQTT — a integração é completamente independente do MQTT.
Esta integração só funciona em um edge home (LAN-only). Dispositivos ESPHome não são expostos pela cloud — eles precisam estar acessíveis na mesma rede do edge.