Shelly MQTT: configuração, topics Gen1/Gen2 e RPC

Os dispositivos Shelly falam MQTT nativamente: abra a interface web do dispositivo, ative o MQTT, informe host, porta e credenciais do seu broker, e o relé começa a publicar o estado e a aceitar comandos. O que muda é a estrutura de topics. Os Gen1 (Shelly 1, 2.5, Plug S, H&T…) usam uma árvore fixa shellies/... com comandos em texto puro, enquanto os Gen2, Plus, Pro e Gen3 usam uma API JSON-RPC que você pode chamar via MQTT.

Este tutorial cobre as duas gerações: as configurações, os topics que você vai ver, como enviar comandos e como verificar tudo pela linha de comando antes de integrar ao Home Assistant, ao openHAB ou ao seu próprio código.

Qual geração você tem?

	Gen1	Gen2 / Plus / Pro / Gen3
Exemplos	Shelly 1, 1PM, 2.5, Plug S, Dimmer 2, H&T	Plus 1PM, Plus Plug S, Pro 4PM, 1 Mini Gen3
Configurações MQTT	Internet & Security → Advanced – Developer Settings	Settings → MQTT (Networks → MQTT nas interfaces novas)
Prefixo padrão	`shellies/<modelo>-<id>`	`<modelo>-<id>` (ex.: `shellyplus1pm-a8032ab12345`)
Payloads	Texto puro (`on`, `off`, números)	JSON (objetos de status, frames RPC)
Nuvem com MQTT ligado	Desativada	Pode continuar ativa
TLS	Depende do firmware	Bundle de CA embutido, sem validação ou CA própria

O ID do dispositivo é derivado do endereço MAC. Ele aparece nas informações do dispositivo na interface web, ou basta assinar # quando o dispositivo estiver conectado e lê-lo nos primeiros topics que chegarem.

Configuração Gen1

Na interface web Gen1, abra Internet & Security → Advanced – Developer Settings e marque Enable action execution via MQTT. Preencha:

Server: broker.connectmq.com:1883
Username / Password: as credenciais do seu broker
Use custom MQTT prefix (opcional): por exemplo testmqtt/shelly/hallway em vez de shellies/shelly1-A1B2C3
Clean session, Keep alive (60 s está bom), Max QoS e Retain: o retain é útil para que um dashboard veja na hora o último estado do relé

Salve, e o dispositivo reinicia a conexão MQTT. Lembre-se de que no Gen1 isso desliga o Shelly Cloud.

Topics Gen1

Topics típicos Gen1 (Shelly 1PM)

shellies/shelly1pm-A1B2C3/online            true | false   (Last Will)
shellies/shelly1pm-A1B2C3/relay/0           on | off
shellies/shelly1pm-A1B2C3/relay/0/power     potência instantânea em W
shellies/shelly1pm-A1B2C3/relay/0/energy    contador de energia (watt-minutos)
shellies/shelly1pm-A1B2C3/input/0           0 | 1
shellies/shelly1pm-A1B2C3/temperature       temperatura interna em °C
shellies/shelly1pm-A1B2C3/relay/0/command   ← publicar on | off | toggle
shellies/announce                           o dispositivo se anuncia (JSON)
shellies/command                            ← publicar announce | update

Os comandos são strings simples. Para acionar o relé, publique on em .../relay/0/command; o dispositivo responde publicando o novo valor em .../relay/0. Publicar announce em shellies/command faz todos os Gen1 do broker informarem ID, IP e firmware, um truque prático de descoberta. Persianas usam roller/0/command com open, close, stop, e roller/0/command/pos com uma porcentagem.

Dispositivos a bateria como o H&T dormem quase o tempo todo: acordam, publicam sensor/temperature e sensor/humidity e desconectam. Faça o lado assinante depender de valores retidos, não do dispositivo estar online.

Configuração Gen2, Plus e Pro

Abra Settings → MQTT e ative:

Server: broker.connectmq.com:8883 (ou :1883 sem TLS)
Client ID: o padrão é o ID do dispositivo; mantenha-o único, veja boas práticas de client ID MQTT
Username / Password
SSL/TLS: No TLS, TLS no validation, TLS with default CA (use com certificados públicos) ou TLS with user CA
MQTT Prefix: o padrão é o ID do dispositivo; defina por exemplo testmqtt/shelly/plug1
RPC status notifications over MQTT: publica eventos em <prefixo>/events/rpc
Generic status update over MQTT: publica o status de cada componente em <prefixo>/status/<componente>
Enable MQTT Control: aceita comandos simples em <prefixo>/command/...

Depois de mudar as configurações MQTT é preciso reiniciar. Você também pode fazer toda a configuração sem a interface, chamando a API RPC via HTTP:

Configurar MQTT em um Gen2 via HTTP RPC

curl -s -X POST http://192.168.1.50/rpc/MQTT.SetConfig \
  -d '{"config":{"enable":true,"server":"broker.connectmq.com:8883","ssl_ca":"ca.pem",
       "user":"username","pass":"password","topic_prefix":"testmqtt/shelly/plug1",
       "rpc_ntf":true,"status_ntf":true,"enable_control":true}}'

curl -s -X POST http://192.168.1.50/rpc/Shelly.Reboot

"ssl_ca": "ca.pem" seleciona o bundle de CA embutido; "*" desativa a validação e "user_ca.pem" usa um certificado que você enviou. Evite "*" fora de um laboratório; veja como testar uma conexão TLS.

Topics Gen2

Topics Gen2 com o prefixo testmqtt/shelly/plug1

testmqtt/shelly/plug1/online              true | false   (Last Will)
testmqtt/shelly/plug1/status/switch:0     {"id":0,"output":true,"apower":12.4,...}
testmqtt/shelly/plug1/events/rpc          {"method":"NotifyStatus","params":{...}}
testmqtt/shelly/plug1/command             ← publicar status_update
testmqtt/shelly/plug1/command/switch:0    ← publicar on | off | toggle
testmqtt/shelly/plug1/rpc                 ← publicar requisições JSON-RPC

Os componentes são endereçados como tipo:índice: switch:0, input:1, cover:0, temperature:100. Com Generic status update ligado, o status completo de cada componente chega no seu próprio topic, o formato mais fácil de consumir. events/rpc carrega deltas NotifyStatus e mensagens NotifyEvent (cliques de botão, por exemplo).

RPC via MQTT

Todo método Gen2 que você chama por HTTP também funciona por MQTT. Publique um frame JSON-RPC em <prefixo>/rpc; o dispositivo responde em <src>/rpc, onde src é o valor que você colocou na requisição. É o clássico padrão request/response.

Requisição publicada em testmqtt/shelly/plug1/rpc

{"id": 1, "src": "testmqtt/shelly/cli", "method": "Switch.Set", "params": {"id": 0, "on": true}}

Resposta em testmqtt/shelly/cli/rpc

{"id": 1, "src": "shellyplusplugs-a8032ab12345", "dst": "testmqtt/shelly/cli", "result": {"was_on": false}}

Métodos úteis: Shelly.GetStatus, Shelly.GetDeviceInfo, Switch.Toggle, Switch.GetStatus, Cover.GoToPosition, Sys.SetConfig. Erros voltam com um objeto error (code e message) em vez de result.

Aqui está um pequeno helper em Python (paho-mqtt 2.x) que envia uma chamada RPC e espera a resposta correspondente:

shelly_rpc.py

import json, os, threading
import paho.mqtt.client as mqtt

PREFIX = "testmqtt/shelly/plug1"
SRC = "testmqtt/shelly/cli"
done = threading.Event()

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe(f"{SRC}/rpc", qos=1)

def on_subscribe(client, userdata, mid, reason_codes, properties):
    req = {"id": 1, "src": SRC, "method": "Shelly.GetStatus"}
    client.publish(f"{PREFIX}/rpc", json.dumps(req), qos=1)

def on_message(client, userdata, msg):
    resp = json.loads(msg.payload)
    if resp.get("id") == 1:
        print(json.dumps(resp.get("result", resp.get("error")), indent=2))
        done.set()

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="shelly-rpc-cli")
client.username_pw_set(os.environ["MQTT_USER"], os.environ["MQTT_PASS"])
client.tls_set()
client.on_connect, client.on_subscribe, client.on_message = on_connect, on_subscribe, on_message
client.connect("broker.connectmq.com", 8883)
client.loop_start()
print("ok" if done.wait(10) else "sem resposta (verifique o prefixo e a opção RPC)")
client.loop_stop()

Teste a configuração

Antes de adicionar o dispositivo a qualquer software de automação residencial, observe o tráfego diretamente:

Ver tudo o que um Shelly publica

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'shellies/#' -t 'testmqtt/shelly/#' -v

Depois acione o relé a partir de um segundo terminal e confira se o topic de estado acompanha:

Enviar comandos

# Gen1
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'shellies/shelly1pm-A1B2C3/relay/0/command' -m toggle

# Gen2 com "Enable MQTT Control"
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/shelly/plug1/command/switch:0' -m toggle

Você pode fazer o mesmo no navegador com o cliente MQTT online: assine o prefixo com #, publique status_update em <prefixo>/command e o dispositivo responde com o status completo. Se não tiver certeza de que um curinga cobre os topics esperados, cole-os no topic matcher.

Veja os topics do seu Shelly no navegador

Se nada aparecer: verifique se o topic online chega a ficar true, se a porta bate com a configuração TLS (8883 com TLS, 1883 sem) e se o dispositivo consegue resolver o nome do broker. Um dispositivo que reconecta sem parar geralmente está disputando com outro cliente que usa o mesmo client ID.

Notas de integração

Home Assistant: os Shelly costumam ser adicionados pela integração nativa Shelly, que não usa MQTT. Se preferir MQTT, defina as entidades manualmente ou use um script de discovery; veja Home Assistant e MQTT.
Design de topics: um prefixo próprio como home/<cômodo>/<dispositivo> mantém Shelly, Tasmota e Zigbee em uma árvore consistente; veja design de topics para casa inteligente.
Estado retido: ative o retain (Gen1) ou use status/... mais uma requisição status_update na inicialização (Gen2) para que os dashboards não mostrem "unknown" após um reinício.
Misturando gerações: escreva seus consumidores para os dois formatos ou normalize-os no Node-RED antes de chegarem à sua aplicação.

O suporte MQTT da Shelly é um dos mais completos do hardware de consumo: topics simples no Gen1 e uma API RPC completa no Gen2 em diante. Configure um prefixo próprio, observe o tráfego com um assinante antes de integrar e restrinja cada dispositivo aos seus próprios topics.

Perguntas frequentes

Ativar o MQTT desativa o Shelly Cloud?

Nos dispositivos Gen1, sim: ligar o MQTT desliga o Shelly Cloud. Nos dispositivos Gen2, Plus, Pro e Gen3, o MQTT e a conexão com a nuvem podem funcionar ao mesmo tempo.

Qual é o topic MQTT padrão de um Shelly?

Os Gen1 usam shellies/<modelo>-<deviceid>/..., por exemplo shellies/shelly1-A1B2C3/relay/0. Os Gen2 e posteriores usam o ID do dispositivo como prefixo, por exemplo shellyplus1pm-a8032ab12345/status/switch:0. Ambos podem ser trocados por um prefixo personalizado.

Os Shelly conseguem se conectar a um broker MQTT via TLS?

Os Gen2 e posteriores suportam TLS com o bundle de CA embutido, sem validação ou com o seu próprio certificado de CA, então a porta 8883 funciona. No Gen1 depende do firmware; o comum é a porta 1883 em uma rede confiável.

Dispositivos Shelly e MQTT: configuração, topics e RPC