ESPHome MQTT: Usando MQTT no Lugar da API Nativa

O suporte a MQTT do ESPHome permite que um ESP32 ou ESP8266 configurado em YAML publique os estados de seus sensores e receba comandos por meio de qualquer broker padrão, em vez da API nativa do Home Assistant. Neste tutorial você vai configurar o componente mqtt:, entender os tópicos que o ESPHome gera, adicionar TLS e credenciais para produção e reagir a mensagens recebidas diretamente no dispositivo.

API Nativa ou MQTT: Quando Trocar

A API nativa do ESPHome é um link ponto a ponto eficiente e criptografado entre um dispositivo e o Home Assistant. Ela é excelente quando o Home Assistant é o único que conversa com o dispositivo. Ela passa a limitar assim que outro software precisa dos mesmos dados: um fluxo do Node-RED, um logger em Python, um pipeline do Grafana via Telegraf ou um segundo local que não alcança a sua LAN.

O MQTT resolve isso colocando um broker no meio. O dispositivo publica uma vez e qualquer número de assinantes recebe a leitura. Nada muda no dispositivo quando você adiciona um novo consumidor, e dispositivos atrás de NAT ainda conseguem alcançar um broker na internet. Se você é novo no modelo publish/subscribe, a visão geral sobre o que um broker MQTT faz é uma boa introdução.

Você pode rodar os dois ao mesmo tempo, mas se nada mais usar a API nativa, remova o bloco api: para que o dispositivo não gaste memória com ela.

Uma Configuração Mínima de ESPHome MQTT

O exemplo abaixo é uma configuração completa para um ESP32 com um sensor DHT22 e um relé, como em uma estufa de mudas de uma fazenda. Ele se conecta ao servidor MQTT público (gratuito) do ConnectMQ para que você veja mensagens em poucos minutos. Substitua a7k2q9 por uma string aleatória sua para que seus tópicos não colidam com os de mais ninguém.

esphome:
  name: greenhouse-node
  friendly_name: Greenhouse Node

esp32:
  board: esp32dev
  framework:
    type: esp-idf

logger:
  level: INFO

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

ota:
  - platform: esphome
    password: !secret ota_password

mqtt:
  broker: broker.connectmq.com
  port: 1883
  client_id: esphome-greenhouse-a7k2q9
  topic_prefix: connectmq/demo/a7k2q9/greenhouse
  discovery: false
  log_topic: null
  birth_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: offline
    retain: true

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    update_interval: 30s
    temperature:
      name: "Air Temperature"
      id: air_temp
    humidity:
      name: "Air Humidity"
      id: air_hum

switch:
  - platform: gpio
    pin: GPIO26
    name: "Vent Fan"
    id: vent_fan

Grave o firmware com esphome run greenhouse-node.yaml. Quando o dispositivo estiver online, assine a partir do seu computador:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/#' -v

Você deve ver o status online retido e uma mensagem de estado a cada 30 segundos para cada sensor.

Configurações que vale a pena entender

• client_id: não pode ser vazio e deve ser único no broker. Se dois dispositivos compartilharem um ID, o broker desconecta a sessão mais antiga toda vez que a mais nova se conecta, e os dois ficam oscilando.
• topic_prefix: o padrão é o nome do nó. Defini-lo explicitamente dá uma hierarquia previsível e mantém o servidor MQTT público organizado.
• discovery: defina como false, a menos que o Home Assistant consuma esse broker. O discovery publica mensagens de configuração retidas sob homeassistant/, que no servidor MQTT público compartilhado ficariam visíveis para todos.
• log_topic: por padrão, o ESPHome espelha seus logs em <prefix>/debug. Definir como null evita que um dispositivo falante estoure os limites de taxa.

Os Tópicos que o ESPHome Publica

O ESPHome monta os tópicos a partir do prefixo, do tipo de componente e de um object ID derivado do nome da entidade (em minúsculas, com espaços virando sublinhados).

Os estados são strings simples: 23.4 para um sensor, ON ou OFF para um interruptor. Para ligar o ventilador pela linha de comando:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/switch/vent_fan/command' -m 'ON'

O dispositivo executa o comando e depois publica o novo estado no tópico state correspondente, de modo que os dashboards sempre refletem o que de fato aconteceu, e não o que foi solicitado.

Se for necessário outro layout de tópicos, todo componente aceita sobrescrever state_topic e command_topic. Isso é útil quando você já tem uma estrutura como a descrita no guia de estrutura de tópicos MQTT para casa inteligente.

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Air Temperature"
      state_topic: connectmq/demo/a7k2q9/site1/greenhouse/temperature

Reagindo a Mensagens MQTT no Dispositivo

O componente MQTT não serve apenas para saída. Você pode disparar automações a partir de qualquer tópico com on_message ou on_json_message e publicar payloads arbitrários com as ações mqtt.publish e mqtt.publish_json.

mqtt:
  # ... configurações de conexão acima ...
  on_message:
    - topic: connectmq/demo/a7k2q9/greenhouse/mode
      payload: "night"
      then:
        - switch.turn_off: vent_fan
  on_json_message:
    topic: connectmq/demo/a7k2q9/greenhouse/setpoint
    then:
      - lambda: |-
          if (x.containsKey("max_temp")) {
            id(max_temp) = x["max_temp"];
          }

globals:
  - id: max_temp
    type: float
    restore_value: true
    initial_value: '28.0'

interval:
  - interval: 60s
    then:
      - if:
          condition:
            lambda: 'return id(air_temp).state > id(max_temp);'
          then:
            - switch.turn_on: vent_fan
            - mqtt.publish_json:
                topic: connectmq/demo/a7k2q9/greenhouse/event
                payload: |-
                  root["event"] = "overheat";
                  root["temp"] = id(air_temp).state;

Isso mantém uma regra de segurança simples no próprio dispositivo, de modo que o ventilador continua funcionando mesmo com a rede fora do ar, enquanto o setpoint pode ser alterado remotamente publicando {"max_temp": 30}.

Configuração de Produção: TLS e Credenciais

O servidor MQTT público serve para testes e protótipos, mas qualquer pessoa pode ler todos os tópicos ali, então ele não é lugar para dados de produção. Para uma instalação real, crie um broker privado e use as credenciais geradas. No ESP32 com o framework ESP-IDF, o ESPHome suporta TLS informando o certificado da CA que assinou o certificado do broker. A ConnectMQ usa um certificado Let's Encrypt, então a CA é a ISRG Root X1.

mqtt:
  broker: broker.connectmq.com
  port: 8883
  client_id: YOUR_CLIENT_ID
  username: YOUR_USERNAME
  password: !secret mqtt_password
  topic_prefix: site1/greenhouse
  discovery: false
  log_topic: null
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    (paste the ISRG Root X1 certificate here)
    -----END CERTIFICATE-----
  birth_message:
    topic: site1/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: site1/greenhouse/status
    payload: offline
    retain: true

Guarde a senha em secrets.yaml em vez do arquivo principal para que ela não acabe no controle de versão. Como na ConnectMQ o client ID fica vinculado às credenciais emitidas, copie-o exatamente do portal.

Placas ESP8266 têm muito menos RAM, e a validação completa de certificado fica apertada nelas. Se você precisar usar TLS em um ESP8266, consulte a documentação atual do ESPHome para ver as opções suportadas, ou migre o projeto para um ESP32, que lida com TLS com folga.

Alimentando o Home Assistant e Outras Ferramentas

Com o dispositivo em um broker, o Home Assistant passa a ser um consumidor entre vários. Aponte a integração MQTT dele para o mesmo broker (o guia de broker MQTT externo para o Home Assistant mostra o passo a passo) e defina discovery: true no dispositivo para que as entidades apareçam automaticamente. Os detalhes do discovery, incluindo os payloads de configuração retidos, estão explicados em MQTT discovery do Home Assistant.

Ao mesmo tempo, um fluxo do Node-RED pode assinar site1/+/sensor/+/state para registrar todos os sensores, e um script Python pode arquivar as leituras em um banco de dados. Nenhum deles precisa saber o endereço IP do dispositivo.

Solução de Problemas no ESPHome MQTT

1. O dispositivo conecta e desconecta a cada poucos segundos. Quase sempre é um client ID duplicado. Verifique se nenhum outro dispositivo ou script de teste esquecido usa o mesmo ID.
2. Nenhuma mensagem aparece. Confirme se a assinatura corresponde exatamente ao prefixo, incluindo maiúsculas e minúsculas. Assine connectmq/demo/a7k2q9/# para ver tudo sob o seu ramo.
3. O handshake TLS falha. Verifique se o dispositivo está com a hora correta (o TLS precisa dela; o ESPHome sincroniza via SNTP), se você colou o bloco PEM completo e se está na porta 8883.
4. Mensagens descartadas no servidor MQTT público. Ele permite 10 mensagens por segundo por cliente e 64 KB por mensagem. Logs no tópico de debug ou intervalos de atualização muito curtos podem ultrapassar isso.
5. Comandos são ignorados. Publique no tópico command, não no state, e use ON ou OFF em maiúsculas para interruptores.

Acompanhar a árvore de tópicos em um explorador ao vivo torna a maioria desses problemas evidente em segundos, e por isso vale a pena abrir o explorador de tópicos do portal ou o app ConnectMQ Desktop enquanto você grava o firmware.

Escalando Além de Alguns Nós

Um único Raspberry Pi rodando um broker funciona até deixar de funcionar: falhas no cartão SD, quedas de energia e redirecionamento de portas para acesso remoto viram problema seu. Migrar para um broker MQTT gerenciado elimina essa manutenção e dá a cada nó ESPHome um endpoint TLS estável que funciona a partir de qualquer rede. O panorama mais amplo de combinar dispositivos, brokers e lógica de automação é abordado no guia de automação com IoT.

Conecte Seus Dispositivos ESPHome à ConnectMQ

A ConnectMQ é um broker MQTT gerenciado que oferece um broker privado com TLS na porta 8883, usuário, senha e client ID gerados e um explorador de tópicos ao vivo para acompanhar seus nós ESPHome reportando. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, cole as credenciais no secrets.yaml e grave o firmware.

Perguntas frequentes

Posso usar o ESPHome MQTT e a API nativa ao mesmo tempo?

Sim. Os dois componentes podem ser habilitados juntos, o que é prático durante uma migração. Remova o api: quando nada mais depender dele, para economizar memória.

O ESPHome MQTT funciona sem o Home Assistant?

Sim. Com discovery: false, o dispositivo simplesmente publica estados e escuta comandos, e qualquer cliente MQTT pode usá-los.

Por que meu dispositivo ESPHome fica reconectando ao broker?

A causa mais comum são dois clientes usando o mesmo client ID. Dê a cada dispositivo um client_id único, ou use exatamente o ID emitido com as credenciais do seu broker.

Qual QoS o ESPHome usa?

As mensagens de estado usam QoS 0 por padrão. Você pode definir qos por componente ou em birth_message e will_message se precisar de garantias de entrega, como explicado no guia de níveis de QoS do MQTT.