Ceci est la référence de ce qu’un appareil publie et auquel il s’abonne. Les règles de connexion, d’authentification et de session se trouvent 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 | Sujet | 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 des attributs partagés, y compris les offres de firmware (fw_*) | Mises à jour du firmware (OTA) |
| Descendant | v1/rpc/req/{id} | Commande 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 description de l’appareil par lui-même (licensed devices) | Appareils sous licence |
| Montant | v1/csr | Demande de signature de certificat (licensed devices) | Certificats d’appareil |
| Descendant | v1/cert | Le certificat émis | identique |
| Montant | v1/claim | Ouvrir ou fermer la fenêtre de revendication (licensed devices) | Ajout et revendication d’appareils |
| Montant | v1/gw/connect, v1/gw/disconnect, v1/gw/telemetry, v1/gw/attributes, v1/gw/attributes/req | Passerelles uniquement : signaler pour les appareils enfants et demander les attributs d’un enfant | Appareils derrière une passerelle |
| Descendant | v1/gw/rpc, v1/gw/attributes, v1/gw/attributes/res | Passerelles uniquement : commandes et attributs partagés pour les appareils enfants, et réponses aux demandes d’attributs | Commands to devices behind a gateway |
| Montant | v1/gw/rpc | Passerelles uniquement : la réponse d’un enfant à une commande | idem |
Un appareil ne peut s’abonner 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 en dehors d’une session de provisionnement | Rejeté avec forbidden_topic. |
Les deux sont acquittés et supprimés. Trois sujets 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és
Les profils avec le schéma Legacy compatible 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 aucun topic de commande, de revendication, de provisionnement ou de passerelle.
Topics personnalisés
Les profils avec Custom topics 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, un texte, du binaire) devient la clé unique
raw, sous forme de texte, jusqu’à Max raw payload (bytes) du profil (4 096 par défaut). - Le topic doit rester dans la Max topic depth (8), la Max topic length (128) et les Distinct topics per device (50) du profil.
- Avec Prefix keys with the topic, chaque clé est stockée sous la forme
<topic>.<key>: les/du sujet deviennent., les autres caractères hors de la règle de clé deviennent_. Par exemplesite1/boilerettempdonnentsite1.boiler.temp. Une clé combinée de plus de 64 caractères est supprimée. Sans le préfixe, la même clé provenant de deux sujets s’écrase elle-même.
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é comme une 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
tsest 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 horodatage.
- Les doublons d’un même appareil, de même clé et de même instant sont stockés une seule fois.
Voir Timestamps, late and duplicate readings.
Clés
- Motif :
^[A-Za-z0-9_.\-]{1,64}$. Les clés sont sensibles à la casse :abcetABCsont deux clés. - Refusées en télémétrie : les clés qui commencent par
_,fw_,current_fw_oucfg.. - Astuce : utilisez des noms en minuscules séparés par des points, par exemple
net.wan.up.
Une clé incorrecte supprime uniquement cette clé ; le reste de l’enregistrement est conservé.
Valeurs
| Valeur JSON | Stockée comme | Règle |
|---|---|---|
| Entier | long | Au-delà de ±2^53, envoyez-la sous forme de chaîne. |
| Fraction | double | NaN et Infinity ne sont pas du JSON et sont refusés. |
true / false | booléen | Les graphiques lisent des nombres : envoyez 0/1 si vous voulez un historique. |
| Chaîne | chaîne | Jusqu’à 1 024 caractères. Affichée comme la dernière valeur, non tracée sur un graphique. |
| Objet ou tableau | JSON | Jusqu’à 4 KiB, stocké tel quel. |
null | rien | Signifie « aucune lecture ». Ne supprime rien. |
Une valeur incorrecte supprime uniquement cette clé.
Taille
- Un message : jusqu’à 64 KiB et jusqu’à 1 000 points clé-valeur. Davantage de points supprime le message entier ; un message plus volumineux est supprimé en totalité. 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 Attributes.
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 contenant 50 lectures coûte le même prix qu’un message avec une seule lecture ; le regroupement permet donc d’économiser du quota.

