Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

Versions du protocole et règles pour l’appareil

Comment le protocole des appareils est versionné, ce qu'un appareil annonce dans hello, les codes d'erreur qu'il utilise et comment il doit réagir en cas de problème.

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

MarqueEmplacementSignification
v1/Le début de chaque topic du schéma par défautLa 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/1Le champ protocol du message hello de l’appareilLa 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.

ChampContenu
modelLe modèle de l’appareil
serialLe 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.
fwLa version du micrologiciel
hwLa révision matérielle
profile_hashUn hachage du profil de paramètres de l’appareil
capabilitiesLes fonctionnalités prises en charge par l’appareil (ci-dessous)
protocolroltek-device-protocol/1

Capacités

Un appareil ne liste que ce qu’il prend en charge.

CapacitéSignification
telemetryEnvoie des mesures
attributesEnvoie des attributs client et reçoit des attributs partagés
rpcReçoit des commandes
rpc.persistentReçoit des commandes conservées jusqu’au retour de l’appareil en ligne
otaReçoit des mises à jour du micrologiciel
cfgReçoit une configuration via les attributs partagés cfg.* (nécessite cfg_hash)
claimPeut être revendiqué pendant une fenêtre de revendication
csrDemande un certificat d’appareil
store_forwardMet en mémoire tampon les mesures hors ligne et les envoie plus tard
gatewayTransmet 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 produitCe que fait Hermetry
JSON imbriqué à plus de 8 niveauxLe abandonne (invalid_payload)
Attributs client ou hello qui ne sont pas un objet JSONLe 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 pasLe abandonne (unknown_reserved_topic)
Un topic sur lequel l’appareil n’est pas autorisé à publierLe abandonne (forbidden_topic)
Trois topics refusés en moins d’une minuteFerme la session
Un SUBSCRIBE sur un topic que l’appareil n’est pas autorisé à lireRépond SUBACK 0x80
Messages dépassant les limites de débit du profilAbandonne 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 :

StatutCode
400invalid_payload, hello_serial_mismatch
413payload_too_large, raw_too_large
429rate_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 :

CodeSignification
unsupported_methodLe destinataire ne connaît pas la méthode
bad_paramsLes paramètres sont absents ou incorrects
busyLe destinataire ne peut pas l’exécuter maintenant
timeoutL’opération a expiré côté destinataire
expiredLe expirationTime de la requête est dépassé
forbiddenLa méthode est désactivée par une politique locale
payload_too_largeLa requête est plus grande que ce que le destinataire accepte
internalTout 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éthodeRéponse
getCurrentTime{"ok": true, "result": {"ts": <heure serveur en ms>}}
getSessionLimitsLes limites effectives par appareil du profil de l’appareil

Règles pour l’appareil

  1. Ignorez ce que vous ne comprenez pas : messages descendants mal formés, clés d’attributs partagés inconnues et champs inconnus.
  2. Répondez à une commande inconnue par unsupported_method ; traitez un code d’erreur inconnu comme internal.
  3. Exécutez un identifiant de commande une seule fois. Une commande peut arriver deux fois ; voir Envoi de commandes aux appareils.
  4. 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.
  5. 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.
  6. 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.
  7. Restez sous vos limites. Demandez-les avec getSessionLimits après la connexion et restez en dessous de 80 % de chacune. Les valeurs par défaut figurent dans Limites et quotas.