Broker MQTT

El hub puede publicar sus mediciones en vivo en un broker MQTT de su red y recibir comandos de él. Home Assistant usa la misma conexión: el hub anuncia sus sensores mediante MQTT discovery.

MQTT está desactivado hasta que configure un broker. El hub se conecta a él solo cuando está en su Wi-Fi doméstica, no cuando funciona solo como punto de acceso propio.

Conectar el hub a un broker

En la aplicación, abra Settings → Home Assistant y rellene el formulario MQTT broker: la dirección del broker, el puerto (normalmente 1883), el usuario y la contraseña. Guarde y reinicie el hub cuando la aplicación lo pida; los ajustes del broker se aplican tras un reinicio.

Por la API: POST /api/system/mqtt-config con {"broker_uri":"mqtt://user:password@host:1883"}. Al leerlo de vuelta, la contraseña aparece enmascarada.

Use una dirección mqtt:// simple, o mqtts:// para una conexión segura:

• desde v1.1.7, con un certificado de una autoridad pública — una de la lista raíz de Mozilla, como Let's Encrypt o DigiCert — que coincida con el nombre de host del broker;
• desde v1.1.8, también con su propia autoridad de certificación: un broker doméstico con una CA privada, o un certificado autofirmado, lo que cubre Mosquitto dentro de Home Assistant con su propio certificado. Véase Your own broker CA más abajo.

En v1.1.7 no se podía usar en absoluto un certificado privado o autofirmado, y un broker así necesitaba una dirección mqtt:// simple en una red de confianza.

Su propia CA del broker

Settings → Home Assistant tiene una tarjeta Broker CA (for mqtts). Mientras no haya nada subido, dice "None uploaded: the hub trusts public certificate authorities only." Upload CA certificate acepta el archivo PEM de su autoridad — el archivo que empieza por -----BEGIN CERTIFICATE----- — y el hub responde "Certificate saved on the hub. It is used after a restart." La tarjeta muestra después lo que contiene: sujeto, emisor y las fechas de validez.

El hub rechaza un archivo que no sirve, y dice por qué:

⚠️ Quitar la CA deja sin conexión a un broker que depende de ella. Remove the broker CA? avisa de que "After a restart the hub connects only to brokers with a public certificate. A broker that uses this CA stops connecting." Después: "Certificate removed. After a restart the hub trusts public certificate authorities only."

La CA subida sustituye al paquete público en lugar de añadirse a él, y se aplica en el siguiente reinicio. Por la API: POST /api/system/mqtt-ca con el PEM, GET para ver lo que está guardado, DELETE para volver al paquete público.

Por qué se rechazó una conexión segura

Desde v1.1.8 el hub comprueba las fechas del certificado además de su autoridad y su nombre de host, y dice lo que ha encontrado. La tarjeta muestra uno de estos mensajes:

⚠️ Un hub sin reloj no abrirá en absoluto una conexión TLS, y es deliberado. Un reloj sin fijar hace que cada certificado parezca "not valid yet", así que desde v1.1.8 el hub espera a tener la hora — por NTP o fijada a mano — antes de intentarlo. El registro de eventos dice "mqtt: TLS broker — waiting for the clock". Un broker mqtt:// simple no se retrasa. → Time

Cada rechazo escribe también una línea en el registro de eventos. Por la API, el mismo estado está en GET /api/system/mqtt-config → tls: {state, ca, ca_uploaded}, donde state es ok, expired, not_yet_valid, name_mismatch, unknown_ca, waiting_clock, connecting, tls_error u off para una conexión simple, y ca es custom o bundle.

Si el hub no puede verificar el broker sigue reintentando, y nada más deja de funcionar: Settings → MQTT muestra MQTT como no conectado, y el registro de eventos del hub indica el motivo. → Events

Mantenga el broker privado. Cualquiera que pueda leer y escribir en el broker puede leer los ajustes del hub a través del canal de comandos, y un token de administrador enviado con un comando es visible para todos los clientes suscritos a él. Use un broker con sus propios usuarios y reglas de acceso (ACL), en su propia red: dé al hub un usuario de broker propio, y limite el acceso a rbgrid/<mac>/# al hub y a los clientes en los que confíe. No use nunca un broker público.

Topics

<mac> es la dirección MAC Wi-Fi del hub: 12 dígitos hexadecimales en minúsculas, por ejemplo a0b1c2d3e4f5. El hub se conecta con el id de cliente rbgrid-<mac>.

La trama de telemetría

Cada trama es un objeto JSON. Los campos principales:

Los valores de energía (e_in, e_out, e_day_in, e_day_out) están en Wh; los valores de dinero (cost_*, rev_*) están en la moneda de la tarifa. En los módulos que cuentan la energía a bordo ("energy_mode": "on_device"), los totales de energía avanzan una vez por periodo de 15 minutos; la potencia, la corriente y la tensión se actualizan cada 3 segundos. Las tramas solo se envían mientras el hub está conectado. Si el broker está caído, las tramas en vivo se descartan (no se guardan en búfer ni se reproducen). El historial se queda en el hub y puede leerse más tarde por HTTP o con el comando history.

Ejemplo

Una trama real de un hub de prueba, acortada a un punto: una línea de cocina que consume unos 400 W. En el cable es una única línea compacta. El total de energía sigue siendo pequeño porque este punto cuenta la energía en el módulo, y el periodo de 15 minutos con la carga aún no había cerrado.

{
  "v": 2,
  "sntp": 1793756448,
  "tq": 1,
  "time_src": "sntp",
  "seq": 707,
  "boot_id": 1158837418,
  "freq": 50,
  "system": {
    "tariff": {
      "zone": "NIGHT",
      "buy_rate": 0.2,
      "sell_rate": 0.12,
      "buy_rate_all_in": 0.27104,
      "currency": "EUR",
      "placeholder": true
    },
    "units": 3,
    "present": 2
  },
  "units": {
    "0102": {
      "point": "kitchen",
      "v": 222.85,
      "i": 1.804,
      "p_act": 402.22,
      "p_rea": 0,
      "pf": 1,
      "dir": 1,
      "present": true,
      "module": 1,
      "ch": 0,
      "ch_label": "I0",
      "energy_mode": "on_device",
      "e_in": 0.0223,
      "e_day_in": 0.0223,
      "e_out": 0,
      "e_day_out": 0,
      "load_pct": 6,
      "type": "CURRENT_LOAD",
      "role": "DEVICE_LOAD"
    }
  },
  "main_unit": "0006",
  "vbus_unit": "0007"
}

"placeholder": true aquí significa que el hub de prueba todavía tenía la tarifa de ejemplo de fábrica.

Discovery de Home Assistant

En cada conexión el hub publica mensajes de discovery con retención, de modo que Home Assistant crea los dispositivos y los sensores por sí solo. Cada sensor lee su valor del topic de telemetría y su disponibilidad del topic de estado (un sensor pasa a unavailable unos 30 segundos después de que el hub deje de enviar).

• Cada punto de medición: corriente (A), potencia (W), potencia reactiva (var), factor de potencia, energía entrante y saliente (Wh, de por vida y de hoy).
• El hub: potencia neta (W) y frecuencia (Hz).
• El bus de tensión: tensión (V).

Los sensores de energía (total_increasing, Wh) van directamente al panel de Energía; véase Integrations.

Cuando elimina (o desvincula) un punto, el hub borra sus mensajes de discovery, y Home Assistant elimina sus entidades. Esto solo funciona mientras el hub esté conectado al broker. Si elimina un punto mientras MQTT está desactivado o el broker está caído, sus entidades siguen en Home Assistant como no disponibles: elimine el dispositivo a mano (Settings → Devices & services → MQTT, el dispositivo, Delete).

Comandos

Publique un comando JSON en rbgrid/<mac>/cmd, con un id que elija usted. La respuesta llega en rbgrid/<mac>/cmd/resp con el mismo id. Varios clientes pueden compartir cmd/resp, así que haga coincidir las respuestas por id.

Leer datos:

{"cmd": "get", "section": "summary", "unit": "0x0100", "period": "day", "id": "q1"}

section puede ser system, telemetry (ajustes), telemetry_data (la trama en vivo), sensors, units, tariff, schema, summary (con unit, period = hour|day|week|month|year, y from/to opcionales como tiempo Unix) o economics (con unit).

Leer el historial:

{"cmd": "history", "unit": "0x0100", "period": "hour", "type": "energy", "offset": 0, "limit": 50, "id": "h1"}

type es electrical, energy, economics, quality o direction; limit llega hasta 720. La respuesta es el mismo JSON que GET /api/v1/history.

Fijar la tarifa:

{"cmd": "set", "section": "tariff", "data": { "...": "the same body as the HTTP tariff call" }, "token": "<admin token>", "id": "t1"}

El token es necesario una vez que hay un token de administrador en el hub. Recuerde que es visible para todos los suscritos a cmd.

Una respuesta correcta es el mismo JSON que el endpoint HTTP correspondiente. Un error tiene este aspecto:

{"type": "cmd_ack", "data": {"cmd": "frobnicate", "result": "error", "message": "unknown cmd (use 'get' / 'set' / 'history')"}, "id": "q2"}

Identifique los hubs por <mac> en el topic: el device_id dentro de las respuestas es el mismo en todos los hubs.

Leer datos sin token en la URL

Desde v1.1.7, las lecturas por MQTT necesitan el token de lectura cuando el hub tiene tokens de lectura y de administrador, igual que las lecturas HTTP: cmd get e history se rechazan sin él. Para un cliente de navegador que no debería llevar un token en la dirección, POST /api/v1/ws-ticket devuelve un ticket de un solo uso válido durante 30 segundos. → Settings → Security

Solución de problemas

No llega nada al broker

• Compruebe que la dirección del broker, el puerto, el usuario y la contraseña son correctos, y que reinició el hub después de guardarlos.
• El hub debe estar en su Wi-Fi doméstica; en modo solo punto de acceso MQTT no arranca.
• Compruebe rbgrid/<mac>/status: online significa que el hub está conectado.

Home Assistant muestra los sensores como no disponibles

• El hub no está enviando: compruebe el topic de estado y la conexión con el broker. Los sensores vuelven en cuanto llegan tramas de nuevo.