Cette page s’adresse aux personnes qui écrivent le micrologiciel des appareils ou le logiciel de passerelle pour Hermetry. Elle explique comment le protocole des appareils est versionné et les règles qu’un appareil suit pour continuer à fonctionner à mesure qu’Hermetry évolue. Les topics et les payloads eux-mêmes figurent dans la référence des topics et payloads MQTT ; les règles de connexion et d’authentification figurent dans MQTT.
Deux marques de version
| Marque | Emplacement | Signification |
|---|---|---|
v1/ | Le début de chaque topic du schéma par défaut | La version des noms de topics. Une modification cassante des topics utiliserait de nouveaux topics sous v2/ ; les topics v1/ ne sont pas renommés. |
roltek-device-protocol/1 | Le champ protocol du message hello de l’appareil | La version majeure du protocole parlé par l’appareil. Hermetry enregistre la version majeure sur l’appareil. |
Les deux marques sont indépendantes : une nouvelle version majeure du protocole ne signifie pas en soi de nouveaux noms de topics.
Le message hello
Un appareil qui se décrit (les appareils sous licence le font) publie sur v1/hello une fois par connexion, avec QoS 1. Les appareils qui n’envoient pas hello continuent de fonctionner avec les topics par défaut.
| Champ | Contenu |
|---|---|
model | Le modèle de l’appareil |
serial | Le numéro de série. Il doit correspondre au numéro de série enregistré de l’appareil, sans quoi le message est refusé avec hello_serial_mismatch. |
fw | La version du micrologiciel |
hw | La révision matérielle |
profile_hash | Un hachage du profil de paramètres de l’appareil |
capabilities | Les fonctionnalités prises en charge par l’appareil (ci-dessous) |
protocol | roltek-device-protocol/1 |
Capacités
Un appareil ne liste que ce qu’il prend en charge.
| Capacité | Signification |
|---|---|
telemetry | Envoie des mesures |
attributes | Envoie des attributs client et reçoit des attributs partagés |
rpc | Reçoit des commandes |
rpc.persistent | Reçoit des commandes conservées jusqu’au retour de l’appareil en ligne |
ota | Reçoit des mises à jour du micrologiciel |
cfg | Reçoit une configuration via les attributs partagés cfg.* (nécessite cfg_hash) |
claim | Peut être revendiqué pendant une fenêtre de revendication |
csr | Demande un certificat d’appareil |
store_forward | Met en mémoire tampon les mesures hors ligne et les envoie plus tard |
gateway | Transmet des rapports pour les appareils enfants |
La liste des capacités du protocole 1 est figée depuis le 23 octobre 2026.
Modifications compatibles et cassantes
Les modifications compatibles conservent la version du protocole. Hermetry peut à tout moment ajouter de nouveaux champs facultatifs, valeurs de capacités, méthodes de commande, clés d’attributs, codes d’erreur et clés de télémétrie. Un appareil doit donc ignorer ce qu’il ne connaît pas : un champ inconnu, une clé d’attribut partagé inconnue, un code d’erreur inconnu.
Les modifications cassantes exigent une nouvelle version majeure : renommer ou supprimer un topic, un champ, une clé d’attribut ou un état ; changer le type ou la signification d’un champ ; ou rendre une limite plus stricte que ne pourrait dépasser un appareil correct de la version actuelle.
Lorsqu’un message est refusé
Le protocole 1 n’a pas de topic d’erreur. Un message qu’Hermetry ne peut pas accepter est abandonné mais tout de même acquitté (PUBACK), afin que l’appareil ne le renvoie pas. Hermetry comptabilise la raison ; elle n’est pas envoyée à l’appareil.
| Ce qui s’est produit | Ce que fait Hermetry |
|---|---|
| JSON imbriqué à plus de 8 niveaux | Le abandonne (invalid_payload) |
Attributs client ou hello qui ne sont pas un objet JSON | Le abandonne (invalid_payload) |
| Mesures qui ne sont pas du JSON du tout (texte, binaire) | Le conserve sous la seule clé raw, jusqu’à la taille brute du profil (raw_too_large au-delà) |
Un topic sous v1/ qui n’existe pas | Le abandonne (unknown_reserved_topic) |
| Un topic sur lequel l’appareil n’est pas autorisé à publier | Le abandonne (forbidden_topic) |
| Trois topics refusés en moins d’une minute | Ferme la session |
| Un SUBSCRIBE sur un topic que l’appareil n’est pas autorisé à lire | Répond SUBACK 0x80 |
| Messages dépassant les limites de débit du profil | Abandonne les messages en trop ; plus de trois fois la limite en 60 secondes ferme la session (rate_limit) |
Over HTTP, l’API de l’appareil répond plutôt par un statut :
| Statut | Code |
|---|---|
| 400 | invalid_payload, hello_serial_mismatch |
| 413 | payload_too_large, raw_too_large |
| 429 | rate_limited, avec un en-tête Retry-After |
Les codes qu’Hermetry enregistre pour les mesures stockées (key_invalid, bad_ts et d’autres) sont listés dans Messages d’erreur.
Codes d’erreur des commandes
Les commandes dans les deux sens (du cloud vers l’appareil sur v1/rpc/req/{id}, de l’appareil vers le cloud sur v1/rpc/up/req/{id}) répondent aux erreurs par {"ok": false, "error": "<code>"} avec l’un de ces codes :
| Code | Signification |
|---|---|
unsupported_method | Le destinataire ne connaît pas la méthode |
bad_params | Les paramètres sont absents ou incorrects |
busy | Le destinataire ne peut pas l’exécuter maintenant |
timeout | L’opération a expiré côté destinataire |
expired | Le expirationTime de la requête est dépassé |
forbidden | La méthode est désactivée par une politique locale |
payload_too_large | La requête est plus grande que ce que le destinataire accepte |
internal | Tout le reste |
Un destinataire traite **tout autre code comme internal**.
Une requête de l’appareil vers le cloud est traitée par vos flux. Si aucun flux ne répond dans les 5 secondes, Hermetry répond unsupported_method. Deux méthodes sont toujours traitées par Hermetry lui-même :
| Méthode | Réponse |
|---|---|
getCurrentTime | {"ok": true, "result": {"ts": <heure serveur en ms>}} |
getSessionLimits | Les limites effectives par appareil du profil de l’appareil |
Règles pour l’appareil
- Ignorez ce que vous ne comprenez pas : messages descendants mal formés, clés d’attributs partagés inconnues et champs inconnus.
- Répondez à une commande inconnue par
unsupported_method; traitez un code d’erreur inconnu commeinternal. - Exécutez un identifiant de commande une seule fois. Une commande peut arriver deux fois ; voir Envoi de commandes aux appareils.
- Renvoyez lorsqu’il n’y a pas d’acquittement. Sans PUBACK dans les 20 secondes, renvoyez le message avec le drapeau DUP ; après trois renvois, reconnectez-vous.
- Relancez une réponse expirée une fois. Si une requête d’attributs ou une requête de l’appareil n’obtient pas de réponse, demandez une fois de plus.
- Temporisez après les connexions refusées. Sur CONNACK 1 (version de protocole non prise en charge), arrêtez les tentatives ; sur CONNACK 3, temporisez normalement ; sur CONNACK 4 ou 5, temporisez longtemps. Les codes figurent dans MQTT.
- Restez sous vos limites. Demandez-les avec
getSessionLimitsaprès la connexion et restez en dessous de 80 % de chacune. Les valeurs par défaut figurent dans Limites et quotas.

