> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# ESPHome

> Conecte dispositivos ESPHome diretamente via API nativa

# 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:

```yaml theme={null}
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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Adicione a integração">
    Vá em **Configurações → Integrações → Adicionar → ESPHome**.
  </Step>

  <Step title="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`
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Tip>
  ESPHome reservou a porta 6053 para essa API. Não há necessidade de configurar um broker MQTT — a integração é completamente independente do MQTT.
</Tip>

<Warning>
  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.
</Warning>