Configuração do Shelly MQTT em Dispositivos Gen2 e Gen3: Topics, RPC e Broker na Nuvem

O suporte a MQTT do Shelly transforma relés, tomadas e medidores de energia Shelly em dispositivos com controle local, que qualquer ferramenta MQTT pode monitorar e comandar. Neste guia você vai ativar o MQTT em dispositivos Shelly Gen2 e Gen3 (as famílias Plus, Pro, Mini e Gen3), entender os topics que eles publicam, controlar saídas com comandos simples e JSON-RPC e conectá-los a um broker via TLS. Todos os exemplos funcionam primeiro com o servidor MQTT público (gratuito), feito para testes.

Como o Shelly MQTT Funciona no Gen2 e Gen3

O firmware de segunda geração do Shelly substituiu o antigo layout de topics do Gen1 (shellies/<id>/relay/0) por uma API baseada em JSON-RPC 2.0. Os mesmos métodos RPC que você pode chamar via HTTP ou WebSocket também estão disponíveis via MQTT, e as mudanças de status são publicadas como notificações. Os dispositivos Gen3 usam a mesma API, então tudo o que vem a seguir vale para ambos.

Cada dispositivo tem um prefixo de topic, que por padrão é o ID do dispositivo, por exemplo shellyplus1pm-a8032ab12345. Você pode trocá-lo por qualquer valor que se encaixe na sua árvore de topics. Sob esse prefixo, os topics importantes são:

Duas configurações controlam o que o dispositivo publica. RPC status notifications envia mensagens NotifyStatus compactas em events/rpc sempre que algo muda. Generic status update publica o status completo do componente nos topics status/<component>. Para a maioria das integrações, os topics de status por componente são mais fáceis de consumir, porque cada mensagem é um retrato completo e não apenas uma diferença.

O dispositivo se comporta como qualquer outro cliente MQTT: abre uma conexão com o broker, publica seu estado e assina seus próprios topics de comando. Se você ainda está formando uma ideia de o que faz um broker MQTT nesse cenário, o ponto principal é que o Shelly nunca conversa diretamente com o seu dashboard; os dois conversam com o broker, e é por isso que um único dispositivo pode alimentar Home Assistant, Node-RED e um script Python ao mesmo tempo sem carga extra no relé.

Ativando o MQTT na Interface Web

Abra a interface web local do dispositivo pelo endereço IP e vá em Settings > MQTT (em algumas versões de firmware fica em Networks > MQTT). Configure:

1. Enable: ative o MQTT.
2. Server: broker.connectmq.com:1883 para um primeiro teste.
3. Client ID: mantenha o padrão ou defina algo único, como shelly-garage-1pm.
4. Username / Password: vazios para o servidor MQTT público.
5. MQTT prefix: troque por algo único, por exemplo connectmq/demo/r7t2/shelly/garage, porque o servidor MQTT público é compartilhado e pode ser lido por todos.
6. Ative RPC status notifications over MQTT e Generic status update over MQTT.
7. Deixe Enable "MQTT Control" ativado se quiser enviar comandos.
8. Salve e reinicie quando solicitado.

O MQTT funciona em paralelo com a interface web local do dispositivo, a API HTTP e as opções de WebSocket de saída, então você não perde o controle local ao ativá-lo. Se você também usa o app de nuvem do Shelly, verifique depois de ativar o MQTT se o app ainda mostra o dispositivo como online na sua versão de firmware.

O prefixo do passo 5 usa cinco níveis de topic, e o Shelly acrescenta mais dois (status/switch:0), o que mantém você dentro do limite de 8 níveis do servidor MQTT público. Se quiser uma árvore mais profunda, encurte o prefixo.

Configurando o Shelly MQTT pela API RPC

Com muitos dispositivos, clicar pela interface é lento. Você pode aplicar a mesma configuração com uma chamada HTTP por dispositivo usando o método Mqtt.SetConfig e depois reiniciar:

SHELLY=192.168.1.50

curl -s -X POST "http://$SHELLY/rpc" -d '{
  "id": 1,
  "method": "Mqtt.SetConfig",
  "params": {
    "config": {
      "enable": true,
      "server": "broker.connectmq.com:1883",
      "client_id": "shelly-garage-1pm",
      "user": null,
      "pass": null,
      "topic_prefix": "connectmq/demo/r7t2/shelly/garage",
      "rpc_ntf": true,
      "status_ntf": true,
      "enable_control": true
    }
  }
}'

curl -s -X POST "http://$SHELLY/rpc" -d '{"id":2,"method":"Shelly.Reboot"}'

Verifique o resultado com curl -s "http://$SHELLY/rpc/Mqtt.GetStatus", que retorna {"connected":true} quando o dispositivo já está conversando com o broker. Se o dispositivo estiver protegido por senha, acrescente --anyauth -u admin:YOUR_DEVICE_PASSWORD às chamadas curl.

Acompanhando as Mensagens do Shelly MQTT

Assine todo o prefixo e acione o relé manualmente ou pelo app:

mosquitto_sub -h broker.connectmq.com -p 1883 -i shelly-watch-4410 \
  -t "connectmq/demo/r7t2/shelly/garage/#" -v

Cada mensagem nos topics de status também é um bom teste do seu prefixo: se aparecerem dispositivos que não são seus na saída, outra pessoa está usando o mesmo prefixo no servidor MQTT público, e você deve escolher um mais aleatório.

Um Shelly Plus 1PM publica um status como este em .../status/switch:0:

{
  "id": 0,
  "source": "WS_in",
  "output": true,
  "apower": 1184.6,
  "voltage": 229.8,
  "current": 5.21,
  "aenergy": { "total": 15832.417, "by_minute": [19542.1, 19688.3, 19601.8], "minute_ts": 1760592120 },
  "temperature": { "tC": 47.3, "tF": 117.2 }
}

As unidades importam: apower está em watts, voltage em volts, current em amperes e aenergy.total é a energia acumulada em watt-hora. Os valores de by_minute estão em miliwatt-hora para os três últimos minutos completos. Dispositivos sem medição, como um Plus 1 simples, não incluem os campos de potência.

Controlando as Saídas

A forma mais simples de acionar uma saída é o topic de comando, que aceita texto puro:

mosquitto_pub -h broker.connectmq.com -p 1883 -i shelly-cmd-4411 \
  -t "connectmq/demo/r7t2/shelly/garage/command/switch:0" -m "on"

Use off ou toggle da mesma forma, e publique status_update em <prefix>/command para que o dispositivo publique imediatamente seu status completo, o que é útil depois que um dashboard reinicia.

Para qualquer coisa além de ligar e desligar, use JSON-RPC. O campo src informa ao dispositivo para onde enviar a resposta: ele publica em <src>/rpc.

mosquitto_pub -h broker.connectmq.com -p 1883 -i shelly-cmd-4412 \
  -t "connectmq/demo/r7t2/shelly/garage/rpc" \
  -m '{"id":10,"src":"connectmq/demo/r7t2/client1","method":"Switch.Set","params":{"id":0,"on":true,"toggle_after":600}}'

Isso liga a saída e a desliga automaticamente após dez minutos, um padrão seguro para bombas e aquecedores. Assine connectmq/demo/r7t2/client1/rpc para ver a resposta, incluindo "was_on".

Uma Integração em Python

O script abaixo assina o status do switch, imprime as leituras de potência e desliga a carga se ela consumir mais que um limite, um exemplo de regra de proteção local que roda fora do dispositivo.

pip install "paho-mqtt>=2.0"

import json
import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/r7t2/shelly/garage"
LIMIT_W = 2000


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)
    client.subscribe(f"{PREFIX}/status/switch:0", qos=1)
    client.subscribe(f"{PREFIX}/online", qos=1)
    client.publish(f"{PREFIX}/command", "status_update")


def on_message(client, userdata, msg):
    if msg.topic.endswith("/online"):
        print("Device online:", msg.payload.decode())
        return
    status = json.loads(msg.payload)
    power = status.get("apower", 0.0)
    energy_kwh = status.get("aenergy", {}).get("total", 0.0) / 1000
    print(f"output={status.get('output')} power={power:.1f} W total={energy_kwh:.3f} kWh")
    if status.get("output") and power > LIMIT_W:
        print("Over limit, switching off")
        client.publish(f"{PREFIX}/command/switch:0", "off", qos=1)


client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="shelly-py-7781")
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_forever()

Para gráficos de energia diária de várias tomadas, veja o tutorial de monitoramento de energia com tomada inteligente MQTT; para medição da casa inteira com um Shelly Pro 3EM ou alicates de corrente (TC), consulte o guia de monitor de energia residencial.

Conectando Dispositivos Shelly com Segurança

O servidor MQTT público serve apenas para testes; qualquer pessoa que conheça seu prefixo pode ler e até acionar seus dispositivos. Em produção, use um broker privado com credenciais e TLS. Os Shelly Gen2 e Gen3 suportam TLS pela opção SSL/TLS nas configurações de MQTT, com três escolhas: sem TLS, TLS com o pacote de CAs embutido ou TLS com uma CA fornecida pelo usuário. Via RPC, o campo ssl_ca controla isso: "ca.pem" usa o pacote embutido, "user_ca.pem" usa uma CA que você enviou e "*" ativa o TLS sem validação de certificado (evite isso fora de testes rápidos).

O ConnectMQ usa certificados Let's Encrypt, que o pacote embutido valida nos firmwares atuais. Uma configuração de produção fica assim:

{
  "enable": true,
  "server": "broker.connectmq.com:8883",
  "client_id": "YOUR_CLIENT_ID",
  "user": "YOUR_USERNAME",
  "pass": "YOUR_PASSWORD",
  "ssl_ca": "ca.pem",
  "topic_prefix": "home/garage/shelly1pm",
  "rpc_ntf": true,
  "status_ntf": true,
  "enable_control": true
}

Como o ConnectMQ vincula os client IDs às credenciais emitidas, cada Shelly deve usar seu próprio conjunto de credenciais do portal, em vez de compartilhar um único login entre dispositivos. Um broker MQTT gerenciado também evita que você tenha de rodar e atualizar um Mosquitto em um servidor doméstico só para manter seus relés acessíveis de fora.

Checklist de Solução de Problemas

Rode seus Dispositivos Shelly no ConnectMQ

O ConnectMQ oferece aos seus relés, tomadas e medidores Shelly um broker privado com TLS na porta 8883, credenciais geradas por dispositivo e um portal com explorador de topics ao vivo para acompanhar cada atualização de status. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito. Para o restante da sua casa inteligente, comece pelo guia de automação com IoT.

Perguntas frequentes

O Shelly MQTT substitui a interface web local?

Não. A interface web e o endpoint RPC via HTTP continuam funcionando com o MQTT ativado, então você ainda pode configurar e acionar o dispositivo localmente mesmo que o broker esteja inacessível.

Qual é a diferença entre events/rpc e os topics de status?

events/rpc transporta notificações JSON-RPC que normalmente contêm apenas o que mudou, enquanto status/<component> transporta um retrato completo de um componente. Retratos completos são mais simples para dashboards e bancos de dados.

Posso usar o Home Assistant com o Shelly MQTT?

Sim. O Home Assistant pode ler os mesmos topics pela integração MQTT, embora muitos usuários prefiram a integração nativa do Shelly e usem o MQTT para outros consumidores, como o Node-RED ou um broker na nuvem.

Os dispositivos Shelly Gen1 usam os mesmos topics?

Não. Os dispositivos Gen1 usam o layout antigo shellies/<device-id>/... e não suportam JSON-RPC, então os exemplos de topics aqui valem apenas para dispositivos Gen2 e Gen3.