Broker MQTT

L'hub può pubblicare le sue misure in tempo reale su un broker MQTT della tua rete e ricevere comandi da esso. Home Assistant usa la stessa connessione: l'hub annuncia i suoi sensori tramite MQTT discovery.

MQTT è disattivato finché non imposti un broker. L'hub si connette al broker solo quando è sulla tua Wi-Fi domestica, non quando funziona solo come punto di accesso proprio.

Collegare l'hub a un broker

Nell'app, apri Settings → Home Assistant e compila il modulo MQTT broker: l'indirizzo del broker, la porta (di solito 1883), il login e la password. Salva e riavvia l'hub quando l'app lo chiede; le impostazioni del broker si applicano dopo un riavvio.

Tramite API invece: POST /api/system/mqtt-config con {"broker_uri":"mqtt://user:password@host:1883"}. Rileggendola, la password appare mascherata.

Usa un indirizzo mqtt:// semplice, oppure mqtts:// per una connessione sicura:

• dalla v1.1.7, con un certificato di un'autorità pubblica — una presente nell'elenco root di Mozilla, come Let's Encrypt o DigiCert — che corrisponda al nome host del broker;
• dalla v1.1.8, anche con una tua autorità di certificazione: un broker domestico con una CA privata, oppure un certificato autofirmato, che copre Mosquitto dentro Home Assistant con un proprio certificato. Vedi Your own broker CA qui sotto.

Sulla v1.1.7 un certificato privato o autofirmato non poteva essere usato affatto, e un broker del genere richiedeva un indirizzo mqtt:// semplice su una rete di cui ti fidi.

La tua CA del broker

Settings → Home Assistant ha una scheda Broker CA (for mqtts). Finché non viene caricato nulla, mostra "None uploaded: the hub trusts public certificate authorities only." Upload CA certificate accetta il file PEM della tua autorità — il file che inizia con -----BEGIN CERTIFICATE----- — e l'hub risponde "Certificate saved on the hub. It is used after a restart." La scheda elenca poi ciò che contiene: soggetto, emittente e le date di validità.

L'hub rifiuta un file non corretto, e dice perché:

⚠️ Rimuovere la CA interrompe un broker che ne dipende. Remove the broker CA? avvisa che "After a restart the hub connects only to brokers with a public certificate. A broker that uses this CA stops connecting." Dopo la rimozione: "Certificate removed. After a restart the hub trusts public certificate authorities only."

La CA caricata sostituisce il bundle pubblico invece di aggiungersi, e si applica al riavvio successivo. Tramite API: POST /api/system/mqtt-ca con il PEM, GET per vedere cosa è memorizzato, DELETE per tornare al bundle pubblico.

Perché una connessione sicura è stata rifiutata

Dalla v1.1.8 l'hub verifica le date del certificato oltre alla sua autorità e al nome host, e dice che cosa ha trovato. La scheda mostra uno di questi messaggi:

⚠️ Un hub senza orologio non apre affatto una connessione TLS, ed è voluto. Un orologio non impostato fa sembrare ogni certificato "not valid yet", quindi dalla v1.1.8 l'hub attende di avere l'ora — via NTP o impostata a mano — prima di provarci. Il registro eventi riporta "mqtt: TLS broker — waiting for the clock". Un broker mqtt:// semplice non viene ritardato. → Time

Ogni rifiuto scrive anche una riga nel registro eventi. Tramite API lo stesso stato si trova in GET /api/system/mqtt-config → tls: {state, ca, ca_uploaded}, dove state è ok, expired, not_yet_valid, name_mismatch, unknown_ca, waiting_clock, connecting, tls_error oppure off per una connessione semplice, e ca è custom oppure bundle.

Se l'hub non riesce a verificare il broker continua a riprovare, e nient'altro smette di funzionare: Settings → MQTT mostra MQTT come non connesso, e il registro eventi dell'hub indica il motivo. → Events

Proteggi il broker. Chiunque possa leggere e scrivere sul broker può leggere le impostazioni dell'hub tramite il canale di comando, e un token di amministratore inviato con un comando è visibile a ogni client iscritto a quel canale. Usa un broker con propri utenti e regole di accesso (ACL), sulla tua rete: dai all'hub un proprio utente sul broker, e limita l'accesso a rbgrid/<mac>/# all'hub e ai client di cui ti fidi. Non usare mai un broker pubblico.

Topic

<mac> è l'indirizzo MAC Wi-Fi dell'hub: 12 cifre esadecimali minuscole, per esempio a0b1c2d3e4f5. L'hub si connette con l'id client rbgrid-<mac>.

Il frame di telemetria

Ogni frame è un unico oggetto JSON. I campi principali:

I valori di energia (e_in, e_out, e_day_in, e_day_out) sono in Wh; i valori monetari (cost_*, rev_*) sono nella valuta della tariffa. Sui moduli che contano l'energia a bordo ("energy_mode": "on_device"), i totali di energia avanzano una volta per periodo di 15 minuti; potenza, corrente e tensione si aggiornano ogni 3 secondi. I frame vengono inviati solo quando l'hub è connesso. Se il broker è giù, i frame in tempo reale vanno persi (nulla viene accodato né riprodotto). La cronologia resta sull'hub e può essere letta in seguito via HTTP o con il comando history.

Esempio

Un frame reale di un hub di prova, accorciato a un solo punto: una linea di cucina che assorbe circa 400 W. Sul filo è una singola riga compatta. Il totale di energia è ancora piccolo perché questo punto conta l'energia sul modulo, e il periodo di 15 minuti con il carico non si era ancora chiuso.

{
  "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 qui significa che l'hub di prova aveva ancora la tariffa di esempio di fabbrica.

Home Assistant discovery

A ogni connessione l'hub pubblica messaggi di discovery trattenuti, così Home Assistant crea da solo dispositivi e sensori. Ogni sensore legge il proprio valore dal topic di telemetria e la propria disponibilità dal topic di stato (un sensore diventa unavailable circa 30 secondi dopo che l'hub smette di inviare).

• Ogni punto di misura: corrente (A), potenza (W), potenza reattiva (var), fattore di potenza, energia in entrata e in uscita (Wh, totale e di oggi).
• L'hub: potenza netta (W) e frequenza (Hz).
• Il bus di tensione: tensione (V).

I sensori di energia (total_increasing, Wh) finiscono direttamente nella dashboard Energy; vedi Integrations.

Quando elimini (o scolleghi) un punto, l'hub cancella i suoi messaggi di discovery, e Home Assistant rimuove le sue entità. Questo funziona solo mentre l'hub è connesso al broker. Se elimini un punto mentre MQTT è spento o il broker è giù, le sue entità restano in Home Assistant come non disponibili: rimuovi il dispositivo a mano (Settings → Devices & services → MQTT, il dispositivo, Delete).

Comandi

Pubblica un comando JSON su rbgrid/<mac>/cmd, con un id a tua scelta. La risposta arriva su rbgrid/<mac>/cmd/resp con lo stesso id. Più client possono condividere cmd/resp, quindi abbina le risposte tramite id.

Leggere dati:

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

section può essere system, telemetry (impostazioni), telemetry_data (il frame in tempo reale), sensors, units, tariff, schema, summary (con unit, period = hour|day|week|month|year, from/to facoltativi come tempo Unix) oppure economics (con unit).

Leggere la cronologia:

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

type è electrical, energy, economics, quality o direction; limit arriva fino a 720. La risposta è lo stesso JSON di GET /api/v1/history.

Impostare la tariffa:

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

Il token serve una volta che sull'hub è impostato un token di amministratore. Ricorda che è visibile a chiunque sia iscritto a cmd.

Una risposta riuscita è lo stesso JSON dell'endpoint HTTP corrispondente. Un errore appare così:

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

Identifica gli hub tramite <mac> nel topic: il device_id nelle risposte è lo stesso su ogni hub.

Leggere i dati senza un token nell'URL

Dalla v1.1.7, le letture MQTT richiedono il token read quando sull'hub sono impostati token di lettura e di amministratore, come per le letture HTTP: cmd get e history vengono rifiutati senza di esso. Per un client browser che non dovrebbe portare un token nell'indirizzo, POST /api/v1/ws-ticket restituisce un ticket monouso valido per 30 secondi. → Settings → Security

Risoluzione dei problemi

Non arriva nulla sul broker

• Verifica che l'indirizzo del broker, la porta, il login e la password siano corretti, e che tu abbia riavviato l'hub dopo averli salvati.
• L'hub deve essere sulla tua Wi-Fi domestica; in modalità solo punto di accesso MQTT non parte.
• Controlla rbgrid/<mac>/status: online significa che l'hub è connesso.

Home Assistant mostra i sensori come non disponibili

• L'hub non sta inviando: controlla il topic di stato e la connessione al broker. I sensori tornano disponibili non appena arrivano di nuovo i frame.