Configurar Shelly MQTT en dispositivos Gen2 y Gen3

Q: ¿Qué diferencia hay entre events/rpc y los topics de estado?

events/rpc transporta notificaciones JSON-RPC que normalmente contienen solo lo que ha cambiado, mientras que status/ transporta una instantánea completa de un componente. Las instantáneas son más sencillas para dashboards y bases de datos.

Q: ¿Usan los mismos topics los dispositivos Shelly Gen1?

No. Los dispositivos Gen1 usan la estructura antigua shellies/ /... y no admiten JSON-RPC, por lo que los ejemplos de topics de esta guía solo se aplican a dispositivos Gen2 y Gen3.

La compatibilidad de Shelly con MQTT convierte los relés, enchufes y medidores de energía Shelly en dispositivos con control local que cualquier herramienta MQTT puede monitorizar y controlar. En esta guía activarás MQTT en dispositivos Shelly Gen2 y Gen3 (las familias Plus, Pro, Mini y Gen3), entenderás los topics que publican, controlarás las salidas con comandos simples y JSON-RPC y los conectarás a un broker mediante TLS. Todos los ejemplos funcionan primero con el servidor MQTT público gratuito, pensado para pruebas y no para datos de producción.

Cómo funciona Shelly MQTT en Gen2 y Gen3

El firmware de segunda generación de Shelly sustituyó la antigua estructura de topics de Gen1 (shellies/<id>/relay/0) por una API basada en JSON-RPC 2.0. Los mismos métodos RPC que puedes invocar por HTTP o WebSocket también están disponibles por MQTT, y los cambios de estado se publican como notificaciones. Los dispositivos Gen3 usan la misma API, así que todo lo que sigue se aplica a ambos.

Cada dispositivo tiene un prefijo de topic, que por defecto es su ID de dispositivo, por ejemplo shellyplus1pm-a8032ab12345. Puedes cambiarlo por cualquier valor que encaje en tu árbol de topics. Bajo ese prefijo, los topics importantes son:

Topic	Dirección	Contenido
`<prefix>/online`	Del dispositivo al broker (retenido)	`true` o `false`; `false` es el Last Will
`<prefix>/events/rpc`	Del dispositivo al broker	Notificaciones JSON-RPC como `NotifyStatus` y `NotifyEvent`
`<prefix>/status/<component>`	Del dispositivo al broker	Estado completo del componente, p. ej. `status/switch:0`, cuando las actualizaciones de estado genéricas están activadas
`<prefix>/rpc`	Del broker al dispositivo	Peticiones JSON-RPC
`<src>/rpc`	Del dispositivo al broker	Respuestas a peticiones RPC, enviadas al `src` que indicaste
`<prefix>/command`	Del broker al dispositivo	Comandos simples como `status_update`
`<prefix>/command/switch:0`	Del broker al dispositivo	`on`, `off` o `toggle` para una salida de interruptor

Dos ajustes controlan lo que publica el dispositivo. RPC status notifications envía mensajes NotifyStatus compactos en events/rpc cada vez que algo cambia. Generic status update publica el estado completo del componente en los topics status/<component>. Para la mayoría de las integraciones, los topics de estado por componente son más fáciles de consumir, porque cada mensaje es una instantánea completa y no un delta.

El dispositivo se comporta como cualquier otro cliente MQTT: abre una conexión con el broker, publica su estado y se suscribe a sus propios topics de comandos. Si todavía estás formándote una idea de qué hace un broker MQTT en este esquema, la clave es que el Shelly nunca habla directamente con tu dashboard; ambos hablan con el broker, y por eso un mismo dispositivo puede alimentar a la vez Home Assistant, Node-RED y un script de Python sin carga adicional para el relé.

Activar MQTT en la interfaz web

Abre la interfaz web local del dispositivo en su dirección IP y ve a Settings > MQTT (en algunas versiones de firmware está en Networks > MQTT). Configura:

Enable: activa MQTT.
Server: broker.connectmq.com:1883 para una primera prueba.
Client ID: deja el valor por defecto o pon algo único como shelly-garage-1pm.
Username / Password: vacíos para el servidor público.
MQTT prefix: cámbialo por algo único, por ejemplo connectmq/demo/r7t2/shelly/garage, porque el broker público es compartido y cualquiera puede leerlo.
Activa RPC status notifications over MQTT y Generic status update over MQTT.
Deja activado Enable "MQTT Control" si quieres enviar comandos.
Guarda y reinicia cuando se te pida.

MQTT funciona junto a la interfaz web local del dispositivo, su API HTTP y sus opciones de WebSocket saliente, así que no pierdes el control local al activarlo. Si también usas la app en la nube de Shelly, comprueba tras activar MQTT que la app sigue mostrando el dispositivo como en línea con tu versión de firmware.

El prefijo del paso 5 usa cinco niveles de topic, y Shelly añade dos más (status/switch:0), con lo que te mantienes dentro del límite de 8 niveles del broker público. Si quieres un árbol más profundo, acorta el prefijo.

Configurar Shelly MQTT mediante la API RPC

Con muchos dispositivos, hacer clic por la interfaz es lento. Puedes aplicar la misma configuración con una llamada HTTP por dispositivo usando el método Mqtt.SetConfig y luego 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"}'

Comprueba el resultado con curl -s "http://$SHELLY/rpc/Mqtt.GetStatus", que devuelve {"connected":true} en cuanto el dispositivo se comunica con el broker. Si el dispositivo está protegido con contraseña, añade --anyauth -u admin:YOUR_DEVICE_PASSWORD a las llamadas curl.

Observar los mensajes de Shelly MQTT

Suscríbete a todo el prefijo y conmuta el relé a mano o desde la app:

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

Cada mensaje en los topics de estado sirve además para probar tu prefijo de topic: si ves dispositivos ajenos en la salida, otra persona está usando el mismo prefijo en el broker público y deberías elegir uno más aleatorio.

Un Shelly Plus 1PM publica un estado como este en .../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 }
}

Aquí las unidades importan: apower está en vatios, voltage en voltios, current en amperios y aenergy.total es la energía acumulada de por vida en vatios-hora. Los valores de by_minute están en milivatios-hora para los tres últimos minutos completos. Los dispositivos sin medición, como un Plus 1 básico, omiten los campos de potencia.

Controlar las salidas

La forma más sencilla de conmutar una salida es el topic de comandos, que acepta texto plano:

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

Usa off o toggle del mismo modo, y publica status_update en <prefix>/command para que el dispositivo publique de inmediato su estado completo, algo muy útil cuando se reinicia un dashboard.

Para cualquier cosa que vaya más allá de encender y apagar, usa JSON-RPC. El campo src indica al dispositivo dónde enviar la respuesta: la publica en <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}}'

Esto enciende la salida y la vuelve a apagar automáticamente al cabo de diez minutos, un patrón seguro para bombas y calefactores. Suscríbete a connectmq/demo/r7t2/client1/rpc para ver la respuesta, que incluye "was_on".

Una integración en Python

El script siguiente se suscribe al estado del interruptor, muestra las lecturas de potencia y apaga la carga si consume más de un límite: un ejemplo de regla de protección local que se ejecuta fuera del 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áficas de energía diaria de varios enchufes, consulta el tutorial de monitorización de energía con enchufes inteligentes MQTT, y para la medición de toda la vivienda con un Shelly Pro 3EM o pinzas amperimétricas, la guía del monitor de energía doméstica.

Conectar los dispositivos Shelly de forma segura

Los brokers públicos son para pruebas; cualquiera que conozca tu prefijo puede leer e incluso conmutar tus dispositivos. En producción, usa un broker privado con credenciales y TLS. Shelly Gen2 y Gen3 admiten TLS mediante la opción SSL/TLS de los ajustes MQTT, con tres posibilidades: sin TLS, TLS con el paquete de CA integrado o TLS con una CA proporcionada por el usuario. Por RPC, esto se controla con el campo ssl_ca: "ca.pem" usa el paquete integrado, "user_ca.pem" usa una CA que hayas subido y "*" activa TLS sin validar el certificado (evítalo fuera de pruebas rápidas).

ConnectMQ usa certificados de Let's Encrypt, que el paquete integrado valida en el firmware actual. Una configuración de producción tiene este aspecto:

{
  "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 ConnectMQ vincula los client IDs a las credenciales emitidas, cada Shelly debería usar su propio juego de credenciales del portal en lugar de compartir un mismo inicio de sesión entre dispositivos. Un broker MQTT gestionado también te ahorra mantener y parchear Mosquitto en un servidor doméstico solo para que tus relés sean accesibles desde fuera.

Lista de comprobación para resolver problemas

Síntoma	Causa probable	Solución
`Mqtt.GetStatus` muestra `connected:false`	Formato host:puerto incorrecto	Usa `host:port` sin `mqtt://`
Se conecta y se desconecta una y otra vez	Dos dispositivos con el mismo client ID	Da a cada dispositivo un ID único
Falla TLS	Firmware antiguo u opción de CA incorrecta	Actualiza el firmware y usa `ca.pem`
No llegan mensajes `status/switch:0`	Generic status update desactivado	Actívalo o usa `events/rpc`
Se ignoran los comandos	Control por MQTT desactivado	Establece `enable_control: true`
Nada tras cambiar el prefijo	El dispositivo no se ha reiniciado	Llama a `Shelly.Reboot`

Ejecuta tus dispositivos Shelly en ConnectMQ

ConnectMQ ofrece a tus relés, enchufes y medidores Shelly un broker privado con TLS en el puerto 8883, credenciales generadas para cada dispositivo y un portal con un explorador de topics en vivo para ver cada actualización de estado. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito. Para el resto de tu hogar inteligente, empieza por la guía de automatización IoT.

Preguntas frecuentes

¿Sustituye Shelly MQTT a la interfaz web local?

No. La interfaz web y el endpoint RPC por HTTP siguen funcionando con MQTT activado, así que puedes seguir configurando y conmutando el dispositivo localmente aunque el broker no esté accesible.

¿Qué diferencia hay entre events/rpc y los topics de estado?

events/rpc transporta notificaciones JSON-RPC que normalmente contienen solo lo que ha cambiado, mientras que status/<component> transporta una instantánea completa de un componente. Las instantáneas son más sencillas para dashboards y bases de datos.

¿Puedo usar Home Assistant con Shelly MQTT?

Sí. Home Assistant puede leer los mismos topics a través de su integración MQTT, aunque muchos usuarios prefieren la integración nativa de Shelly y usan MQTT para otros consumidores como Node-RED o un broker en la nube.

¿Usan los mismos topics los dispositivos Shelly Gen1?

No. Los dispositivos Gen1 usan la estructura antigua shellies/<device-id>/... y no admiten JSON-RPC, por lo que los ejemplos de topics de esta guía solo se aplican a dispositivos Gen2 y Gen3.

Configurar Shelly MQTT en dispositivos Gen2 y Gen3: topics, RPC y broker en la nube