Référence des topics MQTT et des charges utiles

Voici la référence de ce qu’un appareil publie et souscrit. Les règles de connexion, d’authentification et de session figurent dans MQTT. Les appareils HTTP utilisent les mêmes charges utiles ; voir Device HTTP API.

Topics du schéma par défaut

Tous les topics commencent par v1/. Utilisez QoS 1.

Sens	Topic	Usage	Page
Montant	`v1/telemetry`	Télémétrie	ci-dessous
Montant	`v1/attributes`	Attributs client	Attributs
Montant	`v1/attributes/req/{id}`	Demande d’attributs	Attributs
Descendant	`v1/attributes/res/{id}`	Réponse à une demande d’attributs	Attributs
Descendant	`v1/attributes/set`	Modifications d’attributs partagés, y compris les propositions de firmware (`fw_*`)	Mises à jour du firmware (OTA)
Descendant	`v1/rpc/req/{id}`	Commande envoyée depuis le cloud	Envoi de commandes aux appareils
Montant	`v1/rpc/res/{id}`	Réponse à une commande	identique
Montant	`v1/rpc/up/req/{id}`	Requête de l’appareil vers le cloud	identique
Descendant	`v1/rpc/up/res/{id}`	Réponse à une requête de l’appareil	identique
Montant	`v1/provision/req`	Requête de provisionnement (session de provisionnement uniquement)	Ajout et revendication d’appareils
Descendant	`v1/provision/res`	Réponse de provisionnement	identique
Montant	`v1/hello`	La auto-description de l’appareil (appareils sous licence)	Appareils sous licence
Montant	`v1/csr`	Demande de signature de certificat (appareils sous licence)	Certificats d’appareil
Descendant	`v1/cert`	Le certificat émis	identique
Montant	`v1/claim`	Ouvrir ou fermer la fenêtre de revendication (appareils sous licence)	Ajout et revendication d’appareils
Montant	`v1/gw/connect`, `v1/gw/disconnect`, `v1/gw/telemetry`, `v1/gw/attributes`, `v1/gw/attributes/req` (en développement)	Passerelles uniquement : rapport pour les appareils enfants	Appareils derrière une passerelle
Descendant	`v1/gw/attributes`, `v1/gw/attributes/res`, `v1/gw/rpc`	Passerelles uniquement ; en développement (commandes et attributs partagés vers les appareils enfants)	identique

Un appareil ne peut souscrire qu’à ses topics descendants : v1/attributes/set, v1/attributes/res/+, v1/rpc/req/+, v1/rpc/up/res/+ et v1/cert, ainsi que v1/gw/attributes, v1/gw/rpc et v1/gw/attributes/res pour les passerelles. Un appareil ne reçoit jamais les messages d’un autre appareil.

Topics refusés

Publié vers	Résultat
Un topic inconnu sous `v1/`	Rejeté avec `unknown_reserved_topic`, jamais stocké.
Un topic descendant, `v1/gw/*` depuis un appareil qui n’est pas une passerelle, ou `v1/provision/req` hors session de provisionnement	Rejeté avec `forbidden_topic`.

Les deux sont acquittés et ignorés. Trois topics rejetés en une minute ferment la session.

Séquence de connexion

CONNECT
SUBSCRIBE v1/attributes/set      (QoS 1)
SUBSCRIBE v1/attributes/res/+    (QoS 1)
SUBSCRIBE v1/rpc/req/+           (QoS 1)
SUBSCRIBE v1/rpc/up/res/+        (QoS 1, only if the device sends requests)
PUBLISH   v1/attributes/req/1    {}          catch-up: all shared attributes
PUBLISH   v1/attributes          current state
PUBLISH   v1/telemetry           buffered data first, then live data

Topics compatibles héritées

Les profils au schéma Compatible héritage acceptent aussi :

Sens	Topic
Montant	`v1/devices/me/telemetry`
Montant et descendant	`v1/devices/me/attributes`
Montant	`v1/devices/me/attributes/request/{id}`
Descendant	`v1/devices/me/attributes/response/{id}`

Ils ne transportent aucune commande, ni topic de revendication, de provisionnement ou de passerelle.

Topics personnalisés

Les profils avec Topics personnalisés acceptent tout topic hors v1/ comme télémétrie de l’appareil :

Un objet JSON devient des clés. Tout le reste (un nombre, un tableau, du texte, du binaire) devient l’unique clé raw, sous forme de texte, jusqu’à la Taille max. de charge brute (octets) du profil (4 096 par défaut).
Le topic doit rester dans la Profondeur max. de topic (8), la Longueur max. de topic (128) et les Topics distincts par appareil (50) du profil.
Avec Préfixer les clés avec le topic, chaque clé est stockée sous la forme <topic>.<clé> : les / du topic deviennent ., les autres caractères hors règle de clé deviennent _. Par exemple site1/boiler et temp donnent site1.boiler.temp. Une clé jointe de plus de 64 caractères est supprimée. Sans préfixe, la même clé provenant de deux topics s’écrase.

Formes de charge utile de télémétrie

La télémétrie est du JSON, en UTF-8.

Forme A, un objet plat. Un enregistrement, horodaté avec l’heure de réception par Hermetry :

{"temperature": 21.5, "humidity": 40, "door_open": false}

Forme B, un objet contenant exactement ts et values. Un enregistrement à ts :

{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}

Forme C, un tableau d’objets de forme A et de forme B. Un enregistrement par élément, dans l’ordre :

[
  {"ts": 1759572000000, "values": {"sys.cpu_load": 0.42}},
  {"ts": 1759572060000, "values": {"sys.cpu_load": 0.38}},
  {"net.wan.up": true}
]

Pas du JSON. Un corps qui n’est pas du JSON est stocké sous une seule clé raw sur le topic de télémétrie par défaut. Un scalaire JSON (42, "on") sur v1/telemetry est refusé (bad_form).

Un objet contenant ts et values ainsi que tout autre membre est de forme A, et non de forme B : tous ses membres deviennent des clés.

Horodatages

ts est un entier : millisecondes depuis l’époque Unix, en UTC.
Un appareil sans horloge synchronisée doit utiliser la forme A. Il ne doit pas inventer d’horodatage.
Les enregistrements de plus de 10 minutes dans le futur, ou plus anciens que votre rétention de télémétrie, sont supprimés. Ils ne sont jamais déplacés vers un autre instant.
Les doublons d’un même appareil, de même clé et de même instant ne sont stockés qu’une fois.

Voir Horodatages, mesures tardives et en double.

Clés

Motif : ^[A-Za-z0-9_.\-]{1,64}$. Les clés sont sensibles à la casse : abc et ABC sont deux clés.
Refusées en télémétrie : les clés qui commencent par _, fw_, current_fw_ ou cfg..
Astuce : utilisez des noms en minuscules séparés par des points, par exemple net.wan.up.

Une clé incorrecte supprime cette seule clé ; le reste de l’enregistrement est conservé.

Valeurs

Valeur JSON	Stockée comme	Règle
Entier	long	Au-delà de ±2^53, envoyez-le sous forme de chaîne.
Fraction	double	NaN et Infinity ne sont pas du JSON et sont refusés.
`true` / `false`	boolean	Les graphiques lisent des nombres : envoyez `0`/`1` si vous voulez un historique.
Chaîne	string	Jusqu’à 1 024 caractères. Affichée comme dernière valeur, non tracée.
Objet ou tableau	JSON	Jusqu’à 4 KiB, stocké tel quel.
`null`	rien	Signifie « pas de mesure ». Ne supprime rien.

Une valeur incorrecte supprime cette seule clé.

Taille

Un message : jusqu’à 64 KiB et jusqu’à 1 000 points clé-valeur. Au-delà de ces points, tout le message est supprimé ; un message plus volumineux est supprimé en entier. La connexion reste active.
Profondeur d’imbrication : jusqu’à 8 niveaux.
Regroupez vos messages lorsque vous envoyez plus d’un échantillon par seconde.

Attributs client

PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}

Les clés d’attributs peuvent compter jusqu’à 128 caractères. Voir Attributs.

Commandes

PUBLISH v1/rpc/req/42                              (down)
{"method": "sys.ping", "params": {"host": "8.8.8.8", "count": 3}}

PUBLISH v1/rpc/res/42                              (up)
{"ok": true, "result": {"sent": 3, "received": 3, "avg_ms": 18.2}}

PUBLISH v1/rpc/up/req/5                            (up)
{"method": "app.request", "params": {}}

Provisionnement

username: provision, password: empty
SUBSCRIBE v1/provision/res
PUBLISH   v1/provision/req
{"deviceName": "boiler-07", "provisionDeviceKey": "pk_…", "provisionDeviceSecret": "ps_…"}

Ce qui compte comme message

Chaque publication de télémétrie ou d’attributs acceptée compte une fois dans votre quota mensuel de messages, quel que soit son contenu. Les réponses aux commandes, les événements de connexion et les alarmes ne comptent pas. Un message avec 50 mesures coûte autant qu’un message avec une seule mesure : regrouper permet donc d’économiser du quota.