Shelly MQTT Setup for Gen2 and Gen3 Devices: Topics, RPC and Cloud Broker

Shelly MQTT support turns Shelly relays, plugs and energy meters into local-first devices that any MQTT tool can monitor and control. In this guide you will enable MQTT on Gen2 and Gen3 Shelly devices (the Plus, Pro, Mini and Gen3 families), understand the topics they publish, control outputs with plain commands and JSON-RPC, and connect them to a broker over TLS. All examples work first against the free public test broker.

How Shelly MQTT Works on Gen2 and Gen3

Shelly's second-generation firmware replaced the old Gen1 topic layout (shellies/<id>/relay/0) with an API built on JSON-RPC 2.0. The same RPC methods you can call over HTTP or WebSocket are also available over MQTT, and status changes are published as notifications. Gen3 devices use the same API, so everything below applies to both.

Each device has a topic prefix, which defaults to its device ID, for example shellyplus1pm-a8032ab12345. You can change it to anything that fits your topic tree. Under that prefix, the important topics are:

Two settings control what the device publishes. RPC status notifications sends compact NotifyStatus messages on events/rpc whenever something changes. Generic status update publishes the full component status on status/<component> topics. For most integrations, the per-component status topics are easier to consume, because each message is a complete snapshot rather than a delta.

The device behaves like any other MQTT client: it opens one connection to the broker, publishes its state and subscribes to its own command topics. If you are still building a mental model of what an MQTT broker does in this picture, the key point is that the Shelly never talks to your dashboard directly; both talk to the broker, which is why one device can feed Home Assistant, Node-RED and a Python script at the same time without extra load on the relay.

Enabling MQTT in the Web Interface

Open the device's local web UI at its IP address and go to Settings > MQTT (on some firmware versions it is under Networks > MQTT). Configure:

1. Enable MQTT.
2. Server: broker.connectmq.com:1883 for a first test.
3. Client ID: leave the default or set something unique such as shelly-garage-1pm.
4. Username / Password: empty for the public test broker.
5. MQTT prefix: change to something unique, for example connectmq/demo/r7t2/shelly/garage, because the public broker is shared and readable by everyone.
6. Enable RPC status notifications over MQTT and Generic status update over MQTT.
7. Leave Enable "MQTT Control" on if you want to send commands.
8. Save and reboot when prompted.

MQTT runs alongside the device's local web UI, HTTP API and its outbound WebSocket options, so you do not lose local control by enabling it. If you use the Shelly cloud app as well, check after enabling MQTT that the app still shows the device as online on your firmware version.

The prefix in step 5 uses five topic levels, and Shelly adds two more (status/switch:0), which keeps you within the public broker's 8-level limit. If you want a deeper tree, shorten the prefix.

Configuring Shelly MQTT over the RPC API

For many devices, clicking through the UI is slow. You can apply the same configuration with one HTTP call per device using the Mqtt.SetConfig method, then reboot:

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"}'

Check the result with curl -s "http://$SHELLY/rpc/Mqtt.GetStatus", which returns {"connected":true} once the device is talking to the broker. If the device is protected with a password, add --anyauth -u admin:YOUR_DEVICE_PASSWORD to the curl calls.

Watching Shelly MQTT Messages

Subscribe to the whole prefix and toggle the relay by hand or in the app:

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

Every message on the status topics is also a good test of your topic prefix: if you see unrelated devices in the output, someone else is using the same prefix on the public broker, and you should pick a more random one.

A Shelly Plus 1PM publishes a status like this on .../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 }
}

Units matter here: apower is watts, voltage volts, current amperes, and aenergy.total is the lifetime energy in watt-hours. The by_minute values are in milliwatt-hours for the last three complete minutes. Devices without metering, such as a plain Plus 1, omit the power fields.

Controlling Outputs

The simplest way to switch an output is the command topic, which accepts plain text:

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 or toggle the same way, and publish status_update to <prefix>/command to make the device publish its full status immediately, which is handy after a dashboard restarts.

For anything beyond on and off, use JSON-RPC. The src field tells the device where to send the response: it publishes to <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}}'

This turns the output on and automatically off again after ten minutes, which is a safe pattern for pumps and heaters. Subscribe to connectmq/demo/r7t2/client1/rpc to see the response, including "was_on".

A Python Integration

The script below subscribes to the switch status, prints power readings and switches the load off if it draws more than a limit, an example of a local protection rule that runs outside the device.

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()

For per-day energy charts across several plugs, see the smart plug MQTT energy monitoring tutorial, and for whole-house metering with a Shelly Pro 3EM or CT clamps, the home energy monitor guide.

Connecting Shelly Devices Securely

Public brokers are for testing; anyone who knows your prefix can read and even switch your devices. For production, use a private broker with credentials and TLS. Shelly Gen2 and Gen3 support TLS through the SSL/TLS option in the MQTT settings, with three choices: no TLS, TLS with the built-in CA bundle, or TLS with a user-provided CA. Over RPC, the ssl_ca field controls this: "ca.pem" uses the built-in bundle, "user_ca.pem" uses a CA you uploaded, and "*" enables TLS without certificate validation (avoid this outside quick tests).

ConnectMQ uses Let's Encrypt certificates, which the built-in bundle validates on current firmware. A production configuration looks like this:

{
  "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
}

Because ConnectMQ binds client IDs to issued credentials, each Shelly should use its own credential set from the portal rather than sharing one login across devices. A managed MQTT broker also saves you from running and patching Mosquitto on a home server just to keep your relays reachable from outside.

Troubleshooting Checklist

Run Your Shelly Devices on ConnectMQ

ConnectMQ gives your Shelly relays, plugs and meters a private broker with TLS on port 8883, generated credentials per device and a portal with a live topic explorer to watch every status update. Create a free Serverless broker at app.connectmq.com, no credit card required. For the rest of your smart home, start with the IoT automation guide.

Frequently Asked Questions

Does Shelly MQTT replace the local web interface?

No. The web UI and HTTP RPC endpoint keep working when MQTT is enabled, so you can still configure and switch the device locally even if the broker is unreachable.

What is the difference between events/rpc and status topics?

events/rpc carries JSON-RPC notifications that usually contain only what changed, while status/<component> carries a complete snapshot of a component. Snapshots are simpler for dashboards and databases.

Can I use Home Assistant with Shelly MQTT?

Yes. Home Assistant can read the same topics through its MQTT integration, though many users prefer the native Shelly integration and use MQTT for other consumers like Node-RED or a cloud broker.

Do Gen1 Shelly devices use the same topics?

No. Gen1 devices use the older shellies/<device-id>/... layout and do not support JSON-RPC, so the topic examples here apply only to Gen2 and Gen3 devices.