Broker MQTT

Le hub peut publier ses mesures en direct sur un broker MQTT de votre réseau et recevoir des commandes de celui-ci. Home Assistant utilise la même connexion : le hub annonce ses capteurs par MQTT discovery.

MQTT est désactivé tant que vous n'avez pas défini de broker. Le hub ne s'y connecte que lorsqu'il est sur votre Wi-Fi domestique, et non lorsqu'il fonctionne uniquement avec son propre point d'accès.

Connecter le hub à un broker

Dans l'application, ouvrez Settings → Home Assistant et remplissez le formulaire MQTT broker : l'adresse du broker, le port (en général 1883), l'identifiant et le mot de passe. Enregistrez puis redémarrez le hub lorsque l'application le demande ; les réglages du broker prennent effet après un redémarrage.

Par l'API à la place : POST /api/system/mqtt-config avec {"broker_uri":"mqtt://user:password@host:1883"}. La relecture affiche le mot de passe masqué.

Utilisez une adresse mqtt:// simple, ou mqtts:// pour une connexion sécurisée :

• à partir de la v1.1.7, avec un certificat d'une autorité publique — figurant dans la liste racine de Mozilla, comme Let's Encrypt ou DigiCert — qui correspond au nom d'hôte du broker ;
• à partir de la v1.1.8, également avec votre propre autorité de certification : un broker domestique avec une CA privée, ou un certificat auto-signé, ce qui couvre Mosquitto dans Home Assistant avec son propre certificat. Voir Your own broker CA ci-dessous.

Sur la v1.1.7, un certificat privé ou auto-signé ne pouvait pas être utilisé du tout, et un tel broker nécessitait une adresse mqtt:// simple sur un réseau de confiance.

Votre propre CA du broker

Settings → Home Assistant comporte une carte Broker CA (for mqtts). Tant que rien n'est envoyé, elle affiche "None uploaded: the hub trusts public certificate authorities only." Upload CA certificate accepte le fichier PEM de votre autorité — le fichier qui commence par -----BEGIN CERTIFICATE----- — et le hub répond "Certificate saved on the hub. It is used after a restart." La carte liste ensuite ce qu'elle contient : sujet, émetteur et dates de validité.

Le hub refuse un fichier incorrect, et indique pourquoi :

⚠️ Supprimer la CA coupe un broker qui en dépend. Remove the broker CA? avertit que "After a restart the hub connects only to brokers with a public certificate. A broker that uses this CA stops connecting." Après cela : "Certificate removed. After a restart the hub trusts public certificate authorities only."

La CA envoyée remplace le bundle public au lieu de s'y ajouter, et elle s'applique au redémarrage suivant. Par l'API : POST /api/system/mqtt-ca avec le PEM, GET pour voir ce qui est stocké, DELETE pour revenir au bundle public.

Pourquoi une connexion sécurisée a été refusée

À partir de la v1.1.8, le hub vérifie les dates du certificat en plus de son autorité et de son nom d'hôte, et indique ce qu'il a trouvé. La carte affiche l'un de ces messages :

⚠️ Un hub sans horloge n'ouvre aucune connexion TLS, et c'est délibéré. Une horloge non réglée fait paraître chaque certificat « pas encore valide », donc à partir de la v1.1.8 le hub attend d'avoir l'heure — par NTP ou réglée à la main — avant d'essayer. Le journal d'événements indique "mqtt: TLS broker — waiting for the clock". Un broker mqtt:// simple n'est pas retardé. → Time

Chaque refus écrit aussi une ligne dans le journal d'événements. Par l'API, le même état figure dans GET /api/system/mqtt-config → tls: {state, ca, ca_uploaded}, où state vaut ok, expired, not_yet_valid, name_mismatch, unknown_ca, waiting_clock, connecting, tls_error, ou off pour une connexion simple, et ca vaut custom ou bundle.

Si le hub ne peut pas vérifier le broker, il continue de réessayer, et rien d'autre ne s'arrête : Settings → MQTT affiche MQTT comme non connecté, et le journal d'événements du hub indique la cause. → Events

Gardez le broker privé. Toute personne capable de lire et d'écrire sur le broker peut lire les réglages du hub par le canal de commandes, et un jeton d'administrateur envoyé avec une commande est visible par chaque client abonné. Utilisez un broker avec ses propres utilisateurs et règles d'accès (ACL), sur votre propre réseau : donnez au hub son propre utilisateur de broker, et limitez l'accès à rbgrid/<mac>/# au hub et aux clients de confiance. N'utilisez jamais de broker public.

Topics

<mac> est l'adresse MAC Wi-Fi du hub : 12 chiffres hexadécimaux en minuscules, par exemple a0b1c2d3e4f5. Le hub se connecte avec l'identifiant client rbgrid-<mac>.

La trame de télémétrie

Chaque trame est un objet JSON. Les champs principaux :

Les valeurs d'énergie (e_in, e_out, e_day_in, e_day_out) sont en Wh ; les valeurs monétaires (cost_*, rev_*) sont dans la devise du tarif. Sur les modules qui comptent l'énergie à bord ("energy_mode": "on_device"), les totaux d'énergie avancent une fois par période de 15 minutes ; la puissance, le courant et la tension se mettent à jour toutes les 3 secondes. Les trames ne sont envoyées que lorsque le hub est connecté. Si le broker est arrêté, les trames en direct sont perdues (rien n'est mis en mémoire tampon ni rejoué). L'historique reste sur le hub et peut être lu plus tard en HTTP ou avec la commande history.

Exemple

Une vraie trame d'un hub de test, réduite à un seul point : une ligne de cuisine qui tire environ 400 W. Sur le fil, c'est une seule ligne compacte. Le total d'énergie reste faible parce que ce point compte l'énergie dans le module, et que la période de 15 minutes avec la charge n'était pas encore close.

{
  "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 ici signifie que le hub de test utilisait encore le tarif d'exemple d'usine.

Home Assistant discovery

À chaque connexion, le hub publie des messages de discovery conservés, de sorte que Home Assistant crée lui-même les appareils et les capteurs. Chaque capteur lit sa valeur sur le topic de télémétrie et sa disponibilité sur le topic de statut (un capteur passe en unavailable environ 30 secondes après que le hub cesse d'émettre).

• Chaque point de mesure : courant (A), puissance (W), puissance réactive (var), facteur de puissance, énergie entrante et énergie sortante (Wh, depuis l'origine et aujourd'hui).
• Le hub : puissance nette (W) et fréquence (Hz).
• Le bus de tension : tension (V).

Les capteurs d'énergie (total_increasing, Wh) vont directement dans le tableau de bord Énergie ; voir Integrations.

Lorsque vous supprimez (ou détachez) un point, le hub efface ses messages de discovery, et Home Assistant supprime ses entités. Cela ne fonctionne que lorsque le hub est connecté au broker. Si vous supprimez un point alors que MQTT est désactivé ou que le broker est arrêté, ses entités restent dans Home Assistant à l'état indisponible : supprimez l'appareil à la main (Settings → Devices & services → MQTT, l'appareil, Delete).

Commandes

Publiez une commande JSON sur rbgrid/<mac>/cmd, avec un id de votre choix. La réponse arrive sur rbgrid/<mac>/cmd/resp avec le même id. Plusieurs clients peuvent partager cmd/resp, donc associez les réponses par id.

Lire les données :

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

section peut être system, telemetry (réglages), telemetry_data (la trame en direct), sensors, units, tariff, schema, summary (avec unit, period = hour|day|week|month|year, from/to facultatifs en temps Unix) ou economics (avec unit).

Lire l'historique :

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

type vaut electrical, energy, economics, quality ou direction ; limit va jusqu'à 720. La réponse est le même JSON que GET /api/v1/history.

Définir le tarif :

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

Le token est requis dès qu'un jeton d'administrateur est défini sur le hub. Rappelez-vous qu'il est visible de tous les clients abonnés à cmd.

Une réponse réussie est le même JSON que l'endpoint HTTP correspondant. Une erreur ressemble à ceci :

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

Identifiez les hubs par <mac> dans le topic : le device_id présent dans les réponses est identique sur chaque hub.

Lire les données sans jeton dans l'URL

À partir de la v1.1.7, les lectures MQTT exigent le jeton read lorsque le hub a des jetons read et admin définis, comme pour les lectures HTTP : cmd get et history sont refusées sans lui. Pour un client navigateur qui ne doit pas transporter de jeton dans l'adresse, POST /api/v1/ws-ticket renvoie un ticket à usage unique valable 30 secondes. → Settings → Security

Dépannage

Rien n'arrive sur le broker

• Vérifiez que l'adresse du broker, le port, l'identifiant et le mot de passe sont corrects, et que vous avez redémarré le hub après les avoir enregistrés.
• Le hub doit être sur votre Wi-Fi domestique ; en mode point d'accès seul, MQTT ne démarre pas.
• Vérifiez rbgrid/<mac>/status : online signifie que le hub est connecté.

Home Assistant affiche les capteurs comme indisponibles

• Le hub n'émet pas : vérifiez le topic de statut et la connexion au broker. Les capteurs reviennent dès que des trames arrivent à nouveau.