Guia Rápido de Comandos MQTT do Tasmota: Topics cmnd, stat e tele Explicados

Este guia rápido de comandos MQTT do Tasmota reúne os topics e comandos que você vai usar todos os dias para ligar, consultar e ajustar dispositivos Tasmota a partir de qualquer cliente MQTT. Você vai entender como os prefixos cmnd, stat e tele se encaixam, qual payload cada comando espera e como enviá-los de um terminal, de um script ou do cliente web da ConnectMQ.

Como os topics MQTT do Tasmota são montados

Todo topic do Tasmota segue o modelo Full Topic, que por padrão é %prefix%/%topic%/. O nome do comando é acrescentado no final. Para um dispositivo cujo Topic é plug1:

Duas regras evitam a maioria dos erros. Primeiro, os comandos sempre vão para cmnd; publicar em stat não faz nada. Segundo, um payload vazio em um topic de comando consulta o valor atual sem alterá-lo.

Se o seu Full Topic adiciona um prefixo, por exemplo home/%prefix%/%topic%/, todos os topics deste guia ganham esse prefixo: home/cmnd/plug1/POWER. Se você ainda não configurou o MQTT no dispositivo, comece pelo guia de configuração MQTT do Tasmota.

Enviando comandos MQTT ao Tasmota

Você pode enviar qualquer comando deste guia de três maneiras.

Pelo terminal com os clientes do mosquitto. No servidor MQTT público (gratuito), pensado para testes e protótipos, use um prefixo exclusivo no seu Full Topic, como connectmq/demo/k4w9ra/%prefix%/%topic%/:

mosquitto_pub -h broker.connectmq.com -p 1883 -i cli-k4w9ra \
  -t 'connectmq/demo/k4w9ra/cmnd/plug1/POWER' -m 'ON'

Pelo cliente web da ConnectMQ. No portal, abra o cliente MQTT no navegador, assine home/stat/plug1/# e depois publique em home/cmnd/plug1/POWER com o payload TOGGLE. O explorador de topics em tempo real mostra a resposta RESULT ao lado do topic de estado original.

Pelo código. Qualquer biblioteca MQTT funciona; aqui está um exemplo em Python com paho-mqtt 2.x:

import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/k4w9ra"

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="py-k4w9ra")
client.connect("broker.connectmq.com", 1883, keepalive=30)
client.loop_start()
info = client.publish(f"{PREFIX}/cmnd/plug1/POWER", "TOGGLE", qos=1)
info.wait_for_publish()
client.loop_stop()
client.disconnect()

Comandos de energia e relé

PulseTime é a forma segura de criar um interruptor do tipo "ligar por N minutos". Por exemplo, PulseTime1 400 desliga o relé 300 segundos depois de ele ligar, mesmo que a rede caia nesse intervalo.

PowerRetain 1 é útil para dashboards que iniciam depois do dispositivo, pois o último estado do relé é entregue imediatamente na assinatura. Não retenha topics de comando; um cmnd/.../POWER ON retido religaria o relé a cada reconexão.

Comandos de telemetria e status

As respostas ao Status chegam em stat/<topic>/STATUS, STATUS2 e assim por diante, conforme o número. Valores curtos de TelePeriod são práticos durante os testes, mas algumas centenas de dispositivos reportando a cada 10 segundos somam bastante tráfego. Escolha o intervalo mais lento que ainda atenda ao seu dashboard.

Comandos de luz e dimmer

Comandos de configuração

Os group topics facilitam o controle em massa: todo dispositivo com GroupTopic1 kitchen reage a cmnd/kitchen/POWER OFF. O group topic padrão embutido é tasmotas. Se os seus dispositivos compartilham um broker com outras pessoas, troque-o por algo exclusivo; caso contrário, um cmnd/tasmotas/... perdido pode chegar aos seus dispositivos.

Conexões criptografadas têm requisitos próprios, explicados no guia de TLS para MQTT no Tasmota.

Comandos de manutenção

Executando vários comandos com Backlog

O Backlog executa uma lista de comandos separados por ponto e vírgula, que você também pode enviar via MQTT:

mosquitto_pub -h broker.connectmq.com -p 1883 -i cli-k4w9ra \
  -t 'connectmq/demo/k4w9ra/cmnd/plug1/Backlog' \
  -m 'Power ON; Delay 50; Power OFF'

O Delay usa unidades de 0,1 segundo, então Delay 50 espera cinco segundos. O Backlog é a forma mais limpa de enviar uma configuração completa para uma frota de dispositivos sem precisar abrir a interface web de cada um.

Rules: comandos disparados no próprio dispositivo

As Rules permitem que o dispositivo reaja sem nenhum servidor. Um exemplo clássico publica uma mensagem personalizada quando o relé muda de estado:

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

O Publish dentro de uma rule envia para qualquer topic que você quiser, o que é útil quando outro sistema espera um formato específico.

Checklist de referência rápida

1. Envie comandos para cmnd/<topic>/<Command>; leia as respostas em stat/<topic>/RESULT.
2. Payload vazio significa "consultar", não "desligar".
3. Acompanhe tele/<topic>/LWT para saber a disponibilidade.
4. Retenha os topics de estado se os dashboards precisarem; nunca retenha comandos.
5. Use client IDs, topics e group topics exclusivos em brokers compartilhados.

Rode seus dispositivos Tasmota na ConnectMQ

Testar no servidor MQTT público não tem problema, mas ele não serve para dados de produção, e um broker privado mantém estranhos longe dos seus relés, seja em casa ou nas tomadas inteligentes de um galpão de logística. Um broker MQTT gerenciado da ConnectMQ dá a cada dispositivo suas próprias credenciais, um explorador de topics em tempo real para conferir as respostas e TLS na porta 8883 para builds de ESP32. Crie um broker Serverless gratuito em app.connectmq.com sem cartão de crédito e veja o guia de automação IoT para ter ideias de projetos.

Perguntas frequentes

Qual é a diferença entre cmnd, stat e tele no Tasmota?

cmnd é onde você envia comandos, stat transporta respostas e mudanças de estado, e tele transporta a telemetria periódica e a mensagem de disponibilidade Online/Offline.

Como verifico o estado de um dispositivo Tasmota sem acioná-lo?

Publique um payload vazio no topic de comando, por exemplo cmnd/plug1/POWER. O dispositivo responde em stat/plug1/RESULT.

Como envio vários comandos Tasmota em uma única mensagem MQTT?

Publique em cmnd/<topic>/Backlog com os comandos separados por ponto e vírgula, por exemplo Power ON; Delay 50; Power OFF.

Por que meus comandos Tasmota são ignorados?

Geralmente o topic está errado: os comandos precisam usar o prefixo cmnd e corresponder exatamente ao Full Topic do dispositivo, incluindo qualquer prefixo extra e maiúsculas/minúsculas.