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

MQTT

Connecter des appareils via MQTT 3.1.1 : ports, TLS, identifiants de connexion, sessions, accusés de réception, limites, codes CONNACK et manière dont un appareil doit temporiser ses tentatives de reconnexion.

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émentValeur
ProtocoleMQTT 3.1.1 (niveau de protocole 4). Un CONNECT pour MQTT 5 est refusé avec CONNACK 1.
Port, TLS8883
Port, sans chiffrement1883, uniquement pour les appareils d’un profil qui autorise MQTT sans chiffrement
HôteL’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 propreEnvoyez true. Un CONNECT avec false est traité comme une session propre.
KeepaliveUtilisez 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 retainIgnoré. Le message est traité, non conservé.
Délai de connexionEntre 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

IdentifiantClient IDNom d’utilisateurMot de passe
Jeton d’accèstout ID validele jeton d’accèsvide
MQTT de baseau choix, ou le client ID épingléle nom d’utilisateurle mot de passe
Certificat X.509le 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 provision ouvre 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

LimiteValeur par défautOù la définir
Messages de télémétrie10:1,300:60 (10 par seconde et 300 par minute)Limites du profil
Points de données de télémétrie200:1,6000:60Limites du profil
Messages d’attributs5:1,60:60Limites du profil
Taille du message64 Kio, jusqu’à 1 000 points clé-valeurCharge utile maximale du message (octets) du profil
Messages vers l’appareil64 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 ts plus 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

CodeSignificationCe que l’appareil doit faire
0AcceptéContinuer.
1Version du protocole non prise en chargeNe plus réessayer ; corriger le client.
2Client ID refuséAttendre que la configuration change.
3Serveur indisponible : le service est occupé, démarre ou s’arrête, ou l’adresse est brièvement bloquéeTemporiser et réessayer, avec gigue aléatoire.
4Nom d’utilisateur ou mot de passe incorrectTemporiser au moins 5 minutes (jusqu’à 1 heure).
5Non 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 profilTemporiser 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 :

RaisonSignification
client_disconnectL’appareil a fermé la connexion.
keepalive_timeoutRien n’est arrivé pendant le délai de keepalive.
takeoverUne autre connexion du même appareil a pris le relais.
auth_revokedL’identifiant, l’appareil ou l’organisation n’est plus autorisé.
rate_limitL’appareil a continué de dépasser sa limite de débit.
server_shutdownLe nœud broker a redémarré ; reconnectez-vous.
protocol_error, inflight_exceeded, socket_errorLe client a enfreint le protocole, envoyé trop de messages non acquittés, ou le réseau a échoué.

Comportement recommandé de l’appareil

  1. Connectez-vous en TLS par nom d’hôte, avec un keepalive compris entre 30 et 300 secondes.
  2. 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.
  3. Utilisez QoS 1 et attendez le PUBACK avant de supprimer un relevé mis en mémoire tampon.
  4. Regroupez les relevés lorsque vous en envoyez plus d’un par seconde.
  5. 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.

Liens associés