Configuração de MQTT no Tasmota: topics, comandos e telemetria

O Tasmota transforma tomadas inteligentes, relés e sensores baratos com ESP8266 e ESP32 em dispositivos MQTT bem comportados. Aponte-o para um broker, dê um nome de topic e ele passa a aceitar comandos em cmnd/<topic>/…, informar resultados em stat/<topic>/… e enviar telemetria periódica em tele/<topic>/…. Depois que você entende esses três prefixos, consegue controlar qualquer dispositivo Tasmota a partir de qualquer cliente MQTT.

Este guia configura a conexão com o broker, explica Topic e FullTopic, percorre os comandos e a telemetria que você vai usar no dia a dia e testa tudo pelo navegador antes de integrar com Home Assistant ou Node-RED.

Configure o broker

Abra a interface web do dispositivo e vá em Configuration → Configure MQTT:

Ao salvar, o dispositivo reinicia. Você pode fazer o mesmo pelo Console em uma única linha com Backlog, o que ajuda muito ao configurar vários dispositivos:

Backlog MqttHost broker.connectmq.com; MqttPort 1883; MqttUser username; MqttPassword password; MqttClient tasmota-plug1; Topic testmqtt-plug1; FullTopic testmqtt/tasmota/%prefix%/%topic%/

Garanta que o MQTT esteja ativado (Configuration → Configure Other → MQTT enable, ou SetOption3 1). Depois do reinício o console deve mostrar:

MQT: Attempting connection...
MQT: Connected

Se em vez disso aparecer MQT: Connect failed to broker.connectmq.com:1883, rc -2. Retry in 10 sec, o dispositivo não conseguiu abrir uma conexão TCP; rc 4 ou rc 5 significa que as credenciais foram rejeitadas. O guia de Tasmota que não conecta cobre todos os casos.

Topic e FullTopic

O Tasmota monta cada topic MQTT a partir do template FullTopic. Três tokens são substituídos em tempo de execução:

• %prefix% vira cmnd, stat ou tele.
• %topic% vira o Topic do dispositivo (testmqtt-plug1).
• %hostname% e %id% também estão disponíveis se você preferir nomes derivados do chip.

Com o FullTopic padrão %prefix%/%topic%/, uma tomada chamada kitchen usa cmnd/kitchen/POWER. Em um broker de testes compartilhado isso é genérico demais: o seu cmnd/kitchen/POWER colidiria com o de qualquer outra pessoa. O FullTopic acima coloca testmqtt/tasmota/ na frente de tudo, o que dá a você um namespace próprio e facilita as assinaturas:

Em uma instalação maior, escolha um esquema por local ou função e mantenha; o design de topics para casa inteligente traz padrões que escalam.

Comandos: cmnd e stat

Qualquer comando do console pode ser enviado via MQTT. O nome do comando é o último nível do topic e o argumento é o payload:

# Ligar
mosquitto_pub -h broker.connectmq.com -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t testmqtt/tasmota/cmnd/testmqtt-plug1/POWER -m ON

# Alternar
mosquitto_pub -h broker.connectmq.com -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t testmqtt/tasmota/cmnd/testmqtt-plug1/POWER -m TOGGLE

# Consultar o estado: um payload vazio pergunta sem mudar nada
mosquitto_pub -h broker.connectmq.com -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t testmqtt/tasmota/cmnd/testmqtt-plug1/POWER -n

O dispositivo responde em dois topics: stat/testmqtt-plug1/RESULT com JSON como {"POWER":"ON"}, e stat/testmqtt-plug1/POWER com o valor simples ON. Dispositivos com vários relés usam POWER1, POWER2 e assim por diante.

Outros comandos que você vai usar com frequência:

Você também pode enviar Backlog via MQTT, o que transforma a reconfiguração remota de muitos dispositivos em um script de uma linha. Para mais padrões de terminal, veja exemplos de mosquitto_pub e mosquitto_sub.

Telemetria: tele

A cada TelePeriod segundos (300 por padrão) o Tasmota publica duas mensagens:

{"Time":"2026-10-17T10:15:00","Uptime":"0T02:14:31","Heap":25,"POWER":"ON","Wifi":{"SSId":"home","RSSI":72,"Signal":-64}}

{"Time":"2026-10-17T10:15:00","ENERGY":{"Total":3.214,"Yesterday":0.412,"Today":0.183,"Power":46,"Voltage":231,"Current":0.214}}

Os campos exatos dependem do template do dispositivo e dos sensores conectados. tele/.../LWT é especial: o Tasmota publica Online retained depois de conectar e registra Offline como seu Last Will, então os assinantes sempre sabem se o dispositivo está acessível.

Se você precisa de valores mais rápido do que o TelePeriod permite, use uma regra para publicar na mudança. As regras rodam no próprio dispositivo:

Rule1 ON Power1#State DO Publish testmqtt/tasmota/events/testmqtt-plug1 {"power":%value%} ENDON
Rule1 1

Teste tudo pelo navegador

1. Abra o cliente MQTT online e conecte em broker.connectmq.com na porta 8084 com path /mqtt.
2. Assine testmqtt/tasmota/#. Você deve receber na hora o retained tele/testmqtt-plug1/LWT = Online.
3. Publique TOGGLE em testmqtt/tasmota/cmnd/testmqtt-plug1/POWER. O relé estala e stat/.../RESULT e stat/.../POWER chegam em uma fração de segundo.
4. Publique 10 em testmqtt/tasmota/cmnd/testmqtt-plug1/TelePeriod e veja tele/.../STATE chegar a cada dez segundos. Depois volte para um valor razoável.
5. Desconecte o dispositivo da tomada. Após o timeout do keep alive, o broker publica LWT = Offline.

Acompanhe seu dispositivo Tasmota no cliente online

Quando uma assinatura não mostrar nada, compare o filtro com um topic real usando o topic matcher. Um segmento final faltando ou a ordem errada dos prefixos no FullTopic costuma ser o culpado.

Mensagens retained e estado de energia

O Tasmota não marca suas mensagens stat como retained por padrão. Se um dashboard precisa do estado atual logo após assinar, consulte-o (payload vazio em cmnd/.../POWER) ou ative PowerRetain 1 para que stat/.../POWER seja retained.

Nunca publique comandos com o flag retain. Um ON retained em cmnd/.../POWER é reentregue toda vez que o dispositivo reconecta, e o relé liga sozinho após cada queda de energia ou de Wi-Fi. Se isso acontecer, limpe publicando uma mensagem retained vazia no mesmo topic:

mosquitto_pub -h broker.connectmq.com -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t testmqtt/tasmota/cmnd/testmqtt-plug1/POWER -r -n

Mais sobre como a retenção funciona em mensagens retidas no MQTT.

TLS e Home Assistant

O TLS depende do build do firmware. Muitos builds para ESP32 incluem suporte a MQTT TLS, enquanto a maioria dos builds para ESP8266 exige compilar com USE_MQTT_TLS. Em um build com TLS, defina MqttPort 8883 e SetOption103 1 e consulte a documentação de TLS do Tasmota para ver como o seu build valida o certificado do broker. Em builds sem TLS, fique na porta 1883 e use uma rede local confiável.

O Home Assistant usa a integração Tasmota, que lê as mensagens de discovery próprias do Tasmota (ativadas por padrão com SetOption19 0). Aponte a integração MQTT do Home Assistant para o mesmo broker e os dispositivos aparecem automaticamente. O lado do Home Assistant está em Home Assistant MQTT.

O modelo MQTT do Tasmota é simples depois que os prefixos fazem sentido: comandos entram por cmnd, respostas saem por stat e a telemetria chega por tele a cada TelePeriod. Dê a cada dispositivo um client ID único e um FullTopic que mantenha seus dispositivos no próprio namespace, verifique comandos, telemetria e LWT pelo cliente online, e toda automação construída por cima vai se comportar de forma previsível.

Perguntas frequentes