Hermetry parle MQTT 3.1.1. Cette page est la référence de connexion pour les développeurs de appareils : comment atteindre le broker, comment se connecter, comment se comportent les sessions, ce qui est acquitté et quand, et que faire lorsqu’une connexion est refusée. Les topics et les charges utiles sont décrits dans la référence des topics et charges utiles MQTT.
Connexion
| Élément | Valeur |
|---|---|
| Protocole | MQTT 3.1.1 (niveau de protocole 4). Un CONNECT pour MQTT 5 est refusé avec CONNACK 1. |
| Port, TLS | 8883 |
| Port, sans chiffrement | 1883, uniquement pour les appareils d’un profil qui autorise MQTT sans chiffrement |
| Hôte | L’hôte du broker figure sur la carte Détails de connexion de l’appareil. Utilisez l’hôte de la région de votre organisation. |
| Session propre | Envoyez true. Un CONNECT avec false est traité comme une session propre. |
| Keepalive | Utilisez le keepalive MQTT. Un keepalive de 0, ou supérieur au maximum du broker (300 secondes sur une installation par défaut), est ramené au maximum. |
| Message de volonté | Autorisé, ignoré. Hermetry détermine lui-même l’état de la connexion. |
| Indicateur retain | Ignoré. Le message est traité, non conservé. |
| Délai de connexion | Entre la connexion TCP et un CONNECT accepté (poignée de main TLS et authentification incluses), l’appareil dispose de quelques secondes (5 par défaut). |
Rien n’est mis en file d’attente pour un appareil hors ligne, sauf les commandes marquées persistantes. Après chaque connexion, l’appareil se réabonne et demande ses attributs partagés, ce qui lui fournit les valeurs actuelles.
TLS
- TLS 1.2 minimum, TLS 1.3 préféré.
- Suites TLS 1.2 :
ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-CHACHA20-POLY1305. Pas d’échange de clés RSA, pas de CBC. - SNI est obligatoire. Connectez-vous par nom d’hôte, et non par adresse IP.
- Pour les appareils tiers, le certificat serveur est un certificat public. Vérifiez-le avec votre bundle d’autorités de certification habituel et le nom d’hôte.
- Le serveur demande un certificat client sans l’exiger, ainsi un seul port sert tous les types de connexion.
- Les petits appareils peuvent demander des enregistrements TLS de 4 Ko (
max_fragment_length).
Un profil décide si ses appareils peuvent utiliser le port sans chiffrement (MQTT sans chiffrement sur l’onglet Transport et authentification du profil). TLS uniquement est la valeur par défaut. Voir Sécurité du transport des appareils.
Connexion
| Identifiant | Client ID | Nom d’utilisateur | Mot de passe |
|---|---|---|---|
| Jeton d’accès | tout ID valide | le jeton d’accès | vide |
| MQTT de base | au choix, ou le client ID épinglé | le nom d’utilisateur | le mot de passe |
| Certificat X.509 | le numéro de série de l’appareil (doit être égal au CN du certificat) | le numéro de série (ignoré) | vide |
- Un client ID comporte de 1 à 64 caractères parmi
A–Z a–z 0–9 . _ : -. Tout autre caractère est refusé avec CONNACK 2. - Un CONNECT avec un nom d’utilisateur mais sans mot de passe est lu comme un jeton d’accès. Un CONNECT sans nom d’utilisateur est refusé.
- Lorsqu’un certificat client est présenté, c’est lui qui décide. Il n’existe pas de repli vers un mot de passe. Un certificat non approuvé interrompt la poignée de main TLS.
- Le nom d’utilisateur
provisionouvre une session de provisionnement (voir Ajout et revendication des appareils). - Le profil doit autoriser le type d’identifiant, le réseau de l’appareil et le port (TLS ou sans chiffrement) ; sinon la connexion est refusée avec CONNACK 5.
Sessions
- Une session par appareil. Une seconde connexion du même appareil prend le relais et ferme la première. Un appareil dont la session est reprise à plusieurs reprises depuis deux réseaux est mis en attente pendant un certain temps, et vos administrateurs reçoivent une notification (« conflit de reprise ») ; vérifiez que deux appareils ne partagent pas un même identifiant.
- Revérifications. Chaque session active est revérifiée environ toutes les 60 secondes. Un identifiant renouvelé ou révoqué, un appareil désactivé ou supprimé, une organisation suspendue, ou une modification du profil que la session ne respecte plus mettent immédiatement fin à celle-ci.
- Les Quarantined devices se connectent, mais leur télémétrie et leurs attributs sont acquittés et supprimés tant qu’un administrateur ne les a pas activés.
- Notification de nouveau réseau. Lorsqu’un appareil se connecte depuis un autre réseau que la fois précédente, vos administrateurs peuvent recevoir une notification (au plus une fois par heure et par appareil), afin qu’un identifiant volé ne passe pas inaperçu.
- Limite d’appareils connectés. Si votre forfait limite le nombre d’appareils pouvant être connectés simultanément, un CONNECT au-delà de cette limite est refusé avec CONNACK 5.
Acquittements et QoS
- Publiez avec QoS 1. QoS 0 est accepté ; QoS 2 est traité comme QoS 1.
- Hermetry n’envoie le PUBACK qu’une fois le message mis en file d’attente en toute sécurité. Les PUBACK partent dans l’ordre de publication de l’appareil.
- Si un message ne peut pas être mis en file d’attente, il ne reçoit pas de PUBACK (et rien de ce qui suit sur cette session non plus), et la session est fermée après quelques secondes. L’appareil renvoie les messages non acquittés après sa reconnexion.
- Un appareil peut avoir au maximum 20 messages QoS 1 non acquittés en cours par défaut (le paramètre Messages non acquittés max (MQTT) du profil, de 1 à 1 000).
- Les doublons d’un même appareil, de même clé et de même horodatage sont stockés une seule fois ; renvoyer un message est donc sans risque.
Limites
| Limite | Valeur par défaut | Où la définir |
|---|---|---|
| Messages de télémétrie | 10:1,300:60 (10 par seconde et 300 par minute) | Limites du profil |
| Points de données de télémétrie | 200:1,6000:60 | Limites du profil |
| Messages d’attributs | 5:1,60:60 | Limites du profil |
| Taille du message | 64 Kio, jusqu’à 1 000 points clé-valeur | Charge utile maximale du message (octets) du profil |
| Messages vers l’appareil | 64 Kio (4 Kio pour les appareils sous licence) | Charge utile descendante maximale (octets) du profil |
- Au-delà d’une limite de débit, le message est acquitté et supprimé. Un appareil qui dépasse sans cesse sa limite (plus de trois fois son allocation par minute supprimée en une minute) voit sa session fermée. Les propriétaires et administrateurs reçoivent une notification par appareil et par heure.
- Un message trop volumineux est supprimé en totalité ; la connexion reste active.
- Votre organisation dans son ensemble dispose également de limites de débit définies par son forfait.
- Les relevés mis en mémoire tampon qu’un appareil envoie après une panne (chaque enregistrement porte un
tsplus ancien) doivent aussi respecter le paramètre Messages rejoués par seconde du profil. - Les messages de télémétrie et d’attributs comptent dans votre quota mensuel de messages ; les événements de connexion, les commandes et les alarmes n’y comptent pas. Voir Quota de messages et utilisation.
Codes CONNACK
| Code | Signification | Ce que l’appareil doit faire |
|---|---|---|
| 0 | Accepté | Continuer. |
| 1 | Version du protocole non prise en charge | Ne plus réessayer ; corriger le client. |
| 2 | Client ID refusé | Attendre que la configuration change. |
| 3 | Serveur indisponible : le service est occupé, démarre ou s’arrête, ou l’adresse est brièvement bloquée | Temporiser et réessayer, avec gigue aléatoire. |
| 4 | Nom d’utilisateur ou mot de passe incorrect | Temporiser au moins 5 minutes (jusqu’à 1 heure). |
| 5 | Non autorisé : appareil désactivé, certificat révoqué ou expiré, organisation suspendue ou au-delà de sa limite d’appareils ou d’appareils connectés, type de connexion, réseau ou port non autorisé par le profil | Temporiser selon le calendrier long. |
La raison du code 5 n’est jamais envoyée à l’appareil. Elle est écrite dans l’onglet Journal de l’appareil.
Remarque
Des échecs de connexion répétés depuis une même adresse bloquent cette adresse pendant un court instant, pour tous les appareils qui s’y trouvent derrière. Un appareil mal configuré peut donc bloquer ses voisins derrière le même NAT. Corrigez rapidement les identifiants erronés.
Raisons de déconnexion
L’onglet Journal de l’appareil indique pourquoi une session s’est terminée :
| Raison | Signification |
|---|---|
client_disconnect | L’appareil a fermé la connexion. |
keepalive_timeout | Rien n’est arrivé pendant le délai de keepalive. |
takeover | Une autre connexion du même appareil a pris le relais. |
auth_revoked | L’identifiant, l’appareil ou l’organisation n’est plus autorisé. |
rate_limit | L’appareil a continué de dépasser sa limite de débit. |
server_shutdown | Le nœud broker a redémarré ; reconnectez-vous. |
protocol_error, inflight_exceeded, socket_error | Le client a enfreint le protocole, envoyé trop de messages non acquittés, ou le réseau a échoué. |
Comportement recommandé de l’appareil
- Connectez-vous en TLS par nom d’hôte, avec un keepalive compris entre 30 et 300 secondes.
- Après CONNACK 0, abonnez-vous aux topics descendants, demandez les attributs partagés, publiez les attributs client, puis envoyez la télémétrie mise en mémoire tampon avant les données en direct.
- Utilisez QoS 1 et attendez le PUBACK avant de supprimer un relevé mis en mémoire tampon.
- Regroupez les relevés lorsque vous en envoyez plus d’un par seconde.
- En cas de connexion refusée, suivez la temporisation indiquée dans le tableau des CONNACK ; ajoutez une gigue aléatoire pour qu’une flotte ne se reconnecte pas en même temps.

