Tutoriel MQTT : le guide complet pour débuter avec MQTT

Ce tutoriel MQTT vous fait passer de zéro à une configuration publish/subscribe fonctionnelle en une seule séance. Vous apprendrez la poignée de concepts qui font fonctionner MQTT, puis vous exécuterez chaque étape pour de vrai sur le serveur MQTT public gratuit broker.connectmq.com, en ligne de commande, en Python et dans un navigateur. À la fin, vous saurez concevoir des topics, choisir un niveau de QoS, utiliser les retained messages et le Last Will, et savoir quand passer à un broker privé.

Qu'est-ce que MQTT et pourquoi l'apprendre ?

MQTT est un protocole de messagerie publish/subscribe léger qui fonctionne au-dessus de TCP. Il a été conçu pour les réseaux peu fiables et les petits appareils, ce qui explique pourquoi il est aujourd'hui la langue par défaut de l'IoT : capteurs, passerelles, adaptateurs d'automates, applications mobiles et services backend le parlent tous. Les versions actuelles sont MQTT 3.1.1 et MQTT 5.0, toutes deux normalisées par OASIS (le texte complet est publié sur mqtt.org).

Trois propriétés expliquent sa popularité :

• Une surcharge minime. L'en-tête fixe d'un paquet peut ne faire que deux octets, si bien que MQTT fonctionne sur des liaisons cellulaires, par satellite ou sur un Wi-Fi saturé.
• Le découplage. Les éditeurs ne parlent jamais directement aux abonnés. Ils n'ont pas besoin de connaître leurs adresses IP respectives, ni même d'être en ligne en même temps.
• Le push plutôt que le polling. Dès qu'un client s'abonne, les données arrivent au moment même où elles sont publiées. Aucune boucle de requêtes ne vient consommer batterie et bande passante.

Si vous voulez examiner le flux de paquets en détail avant de mettre les mains dans le cambouis, lisez comment MQTT fonctionne sous le capot. Sinon, continuez : les concepts ci-dessous suffisent pour construire des systèmes réels.

Les concepts clés en cinq minutes

Broker

Le broker est le serveur au centre. Chaque client ouvre vers lui une connexion TCP de longue durée, et le broker achemine chaque message publié vers tous les clients dont l'abonnement correspond. Il suit aussi les sessions, conserve les retained messages et déclenche les messages Last Will. Pour une explication complète de ce que fait un broker MQTT, y compris ce qui le distingue d'une file de messages, consultez notre guide dédié.

Clients

Tout ce qui se connecte au broker est un client : un ESP32, un script Python, un flow Node-RED, un tableau de bord dans un navigateur. Un client peut publier, s'abonner, ou les deux. Chaque connexion porte un client ID, que le broker utilise pour identifier la session. Deux clients ayant le même ID s'éjectent mutuellement : veillez donc toujours à ce qu'il soit unique.

Topics

Un topic est une chaîne UTF-8 dont les niveaux sont séparés par des barres obliques, par exemple factory1/line2/press3/temperature. Les topics ne sont pas créés à l'avance ; ils existent dès que quelqu'un y publie. Une bonne conception des topics est la décision la plus importante d'un projet MQTT, c'est pourquoi nous la détaillons dans les conventions de nommage des topics MQTT.

Publier et s'abonner

Un éditeur envoie un message sur un topic. Un abonné déclare son intérêt pour un filtre de topic. Le broker fait correspondre les deux. C'est le modèle publish/subscribe, et c'est lui qui vous permet d'ajouter un nouveau tableau de bord ou un nouveau writer de base de données sans toucher à un seul appareil.

Wildcards

Les abonnés peuvent utiliser deux wildcards :

• + correspond à exactement un niveau : factory1/+/press3/temperature
• # correspond à tous les niveaux restants et doit être en dernière position : factory1/#

Les éditeurs ne peuvent jamais utiliser de wildcards. Les règles de correspondance complètes, y compris les cas limites autour des topics $SYS, se trouvent dans notre guide des wildcards MQTT.

Étape 1 : choisir un broker pour ce tutoriel MQTT

Il vous faut un broker avec lequel communiquer. En installer un en local fonctionne, mais cela ajoute la gestion du pare-feu, des ports et du service à votre première heure. Le plus rapide est d'utiliser un broker public de test. Dans ce tutoriel, nous utilisons broker.connectmq.com, le serveur MQTT public gratuit exploité par ConnectMQ. Il accepte les connexions anonymes sur tous les ports standard :

Les règles à connaître avant de commencer :

1. Utilisez un client ID non vide et unique à chaque connexion.
2. Préfixez tous vos topics par quelque chose que personne d'autre n'utilisera, comme connectmq/demo/<random-id>/. Choisissez votre identifiant aléatoire dès maintenant, par exemple a7k2q9.
3. Tout ce qui se trouve dans l'espace public est lisible par tous. Ne publiez jamais de mots de passe, de données personnelles ni quoi que ce soit de sensible.
4. Le serveur MQTT public gratuit a des limites : 64 Ko par message, 10 messages par seconde et par client, 10 abonnements par client, jusqu'à 8 niveaux de topic et des sessions qui expirent au bout de 30 minutes au maximum. Elles sont généreuses pour apprendre et volontairement trop faibles pour la production.

Si vous voulez comprendre pourquoi ces quatre ports existent et lequel choisir derrière un pare-feu d'entreprise, lisez les ports MQTT expliqués.

Étape 2 : votre premier publish et subscribe en ligne de commande

Les clients en ligne de commande de Mosquitto sont le moyen le plus simple de voir MQTT à l'œuvre. Installez-les avec votre gestionnaire de paquets :

# Debian / Ubuntu / Raspberry Pi OS
sudo apt install mosquitto-clients

# macOS (Homebrew)
brew install mosquitto

Sous Windows, l'installateur du projet Mosquitto inclut mosquitto_pub.exe et mosquitto_sub.exe.

Ouvrez un terminal et abonnez-vous à tout ce qui se trouve sous votre préfixe. L'option -v affiche le topic à côté de chaque payload :

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t "connectmq/demo/a7k2q9/#" -v

Ouvrez un second terminal et publiez :

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t "connectmq/demo/a7k2q9/room1/temperature" -m "21.5"

Le premier terminal affiche immédiatement connectmq/demo/a7k2q9/room1/temperature 21.5. Voilà toute la boucle MQTT : se connecter, s'abonner, publier, recevoir.

Essayez maintenant le port chiffré. Comme broker.connectmq.com utilise un certificat Let's Encrypt, le magasin de CA de votre système peut le vérifier :

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i pub-tls-a7k2q9 -t "connectmq/demo/a7k2q9/room1/humidity" -m "48"

Sous macOS ou Windows, pointez --cafile vers un fichier de bundle CA au lieu d'utiliser --capath.

Étape 3 : QoS, retained messages et Last Will

Ces trois fonctionnalités sont ce qui distingue MQTT d'un simple socket. Essayez-les dès maintenant.

Qualité de service

Chaque publication et chaque abonnement portent un niveau de QoS :

La QoS effective pour un abonné est la plus faible entre la QoS de publication et la QoS d'abonnement. Publiez avec -q 1 et abonnez-vous avec -q 1 pour observer une livraison acquittée. Notre guide pour choisir entre QoS 0, 1 et 2 détaille les compromis à travers des scénarios de panne réels.

Retained messages

Un retained message est stocké par le broker comme « dernière valeur connue » d'un topic et transmis instantanément à tout nouvel abonné. Publiez-en un :

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 -r \
  -t "connectmq/demo/a7k2q9/room1/setpoint" -m "22"

Lancez maintenant un nouvel abonné. Il reçoit 22 immédiatement, même si rien n'a été publié après sa connexion. Pour effacer un retained message, publiez un payload vide avec le flag retain : -r -n. D'autres patterns, notamment les cas où les retained messages sèment la confusion, sont présentés dans les retained messages MQTT.

Last Will and Testament

À la connexion, un client peut enregistrer un message « testament ». Si le client disparaît sans déconnexion propre (coupure de courant, perte de réseau, plantage), le broker publie ce testament en son nom. Combinez-le avec un message « online » retenu et vous obtenez une détection de présence fiable :

mosquitto_sub -h broker.connectmq.com -p 1883 -i dev-a7k2q9 \
  -t "connectmq/demo/a7k2q9/room1/cmd" \
  --will-topic "connectmq/demo/a7k2q9/room1/status" \
  --will-payload "offline" --will-retain --will-qos 1 -k 10

Tuez ce processus avec le bouton de fermeture de votre terminal (et non Ctrl+C, qui peut encore envoyer une déconnexion propre sur certaines versions) et regardez offline arriver sur votre abonné wildcard après environ une fois et demie l'intervalle de keep-alive.

Étape 4 : le même tutoriel MQTT en Python

La ligne de commande est idéale pour explorer ; les vrais projets utilisent une bibliothèque. Installez paho-mqtt 2.x :

pip install "paho-mqtt>=2.0"

Ce script se connecte en MQTT 5, s'abonne à son propre topic de commande, publie une mesure toutes les cinq secondes et annonce sa présence avec un statut retenu et un Last Will :

import json
import random
import time
import uuid

import paho.mqtt.client as mqtt

BROKER = "broker.connectmq.com"
PREFIX = "connectmq/demo/a7k2q9"
CLIENT_ID = f"tutorial-py-{uuid.uuid4().hex[:8]}"


def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print(f"Connect failed: {reason_code}")
        return
    print("Connected as", CLIENT_ID)
    client.publish(f"{PREFIX}/room1/status", "online", qos=1, retain=True)
    client.subscribe(f"{PREFIX}/room1/cmd", qos=1)


def on_message(client, userdata, msg):
    print(f"Command on {msg.topic}: {msg.payload.decode()}")


def on_disconnect(client, userdata, flags, reason_code, properties):
    print(f"Disconnected: {reason_code}")


client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id=CLIENT_ID,
    protocol=mqtt.MQTTv5,
)
client.will_set(f"{PREFIX}/room1/status", "offline", qos=1, retain=True)
client.on_connect = on_connect
client.on_message = on_message
client.on_disconnect = on_disconnect

client.tls_set()  # vérifie le certificat Let's Encrypt avec les CA du système
client.connect(BROKER, 8883, keepalive=30)
client.loop_start()

try:
    while True:
        reading = {"temperature": round(random.uniform(19, 24), 2), "ts": int(time.time())}
        client.publish(f"{PREFIX}/room1/telemetry", json.dumps(reading), qos=1)
        time.sleep(5)
except KeyboardInterrupt:
    client.publish(f"{PREFIX}/room1/status", "offline", qos=1, retain=True).wait_for_publish()
    client.disconnect()
    client.loop_stop()

Laissez votre terminal mosquitto_sub ouvert et vous verrez la télémétrie défiler. Renvoyez une commande avec mosquitto_pub -t "connectmq/demo/a7k2q9/room1/cmd" -m "reboot" et le script l'affiche. Notez les particularités de paho 2.x : CallbackAPIVersion.VERSION2 est obligatoire, et les callbacks reçoivent les arguments reason_code et properties. Mélanger d'anciens exemples 1.x est la source d'erreurs la plus fréquente ici.

Étape 5 : MQTT dans le navigateur avec WebSocket

Les navigateurs ne peuvent pas ouvrir de sockets TCP bruts ; ils parlent donc MQTT sur WebSocket. Enregistrez ceci sous index.html et ouvrez-le dans n'importe quel navigateur moderne :

// Chargez d'abord MQTT.js depuis un CDN dans votre HTML :
// <script src="https://unpkg.com/mqtt@5.10.1/dist/mqtt.min.js"></script>

const clientId = "tutorial-web-" + Math.random().toString(16).slice(2, 10);
const prefix = "connectmq/demo/a7k2q9";

const client = mqtt.connect("wss://broker.connectmq.com:8084/mqtt", {
  clientId,
  protocolVersion: 5,
  clean: true,
  reconnectPeriod: 2000,
});

client.on("connect", () => {
  console.log("Connected", clientId);
  client.subscribe(`${prefix}/#`, { qos: 1 });
  client.publish(`${prefix}/room1/cmd`, "hello from the browser", { qos: 1 });
});

client.on("message", (topic, payload) => {
  console.log(topic, payload.toString());
});

client.on("error", (err) => console.error("MQTT error", err.message));

Ouvrez la console de développement : vous verrez la télémétrie Python, la consigne et le statut retenus, ainsi que votre propre commande renvoyée en écho. Le port 8084 avec le chemin /mqtt est celui à utiliser depuis des pages HTTPS, car les navigateurs bloquent les connexions WebSocket non sécurisées depuis des origines sécurisées. Notre guide MQTT sur WebSocket couvre les proxys, les frameworks et l'authentification dans le navigateur.

Concevoir des topics et des payloads qui passent à l'échelle

Une fois que les messages circulent, c'est la conception qui détermine si le système reste maintenable. Quelques règles qui ont fait leurs preuves :

1. Allez du général au particulier. site/area/line/device/measurement vous permet de vous abonner à toute une ligne avec un seul wildcard.
2. Ne commencez pas par une barre oblique. /factory/line1 crée un premier niveau vide qui complique chaque filtre.
3. Gardez des identifiants stables. Utilisez des ID d'appareils, pas des noms lisibles qui changeront.
4. Séparez les données des commandes. .../telemetry, .../status et .../cmd doivent être des topics distincts, afin que les permissions et la QoS puissent différer.
5. Choisissez un seul format de payload. JSON est lisible et facile à déboguer ; les formats binaires comme Protobuf économisent de la bande passante sur les liaisons contraintes. Quel que soit votre choix, incluez un horodatage et des unités.
6. Évitez un topic par mesure. Publier dix valeurs sur dix topics chaque seconde multiplie la surcharge des paquets ; un petit objet JSON est généralement préférable.

Pour les systèmes industriels, une hiérarchie alignée sur ISA-95 (entreprise, site, zone, ligne, cellule) est devenue une convention courante, et c'est la base du pattern Unified Namespace expliqué dans Sparkplug B et le Unified Namespace.

Erreurs courantes de débutant et comment les corriger

Du tutoriel à la production

Un broker public est idéal pour apprendre, et rien de plus. Avant la mise en service d'appareils réels, il vous faut des identifiants privés, du TLS partout, une isolation vis-à-vis des autres utilisateurs et des limites dimensionnées pour votre parc. Vous pouvez exploiter votre propre broker, mais vous prenez alors en charge les correctifs, les certificats, la supervision et la planification de capacité. Un broker MQTT managé transfère ce travail au fournisseur.

Avec ConnectMQ, le passage se résume pour l'essentiel à un changement de configuration. Inscrivez-vous, choisissez un plan, créez un broker, et le portail vous fournit un nom d'utilisateur, un mot de passe et un client ID générés. Le code de ce tutoriel fonctionne tel quel une fois les identifiants ajoutés :

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="YOUR_CLIENT_ID",
    protocol=mqtt.MQTTv5,
)
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.connect("broker.connectmq.com", 8883, keepalive=30)

Le portail inclut aussi un client MQTT dans le navigateur et un explorateur de topics en direct, pour que vous puissiez refaire chaque étape de ce tutoriel sur votre broker privé sans rien installer. Pour comparer les options de déploiement, d'une offre serverless mutualisée à un cluster dédié ou à votre propre compte cloud, lisez notre guide pour choisir un broker MQTT cloud. Parcourez ensuite les bonnes pratiques de sécurité MQTT avant de connecter le premier appareil sur le terrain.

Votre parcours d'apprentissage après ce tutoriel

Démarrer avec ConnectMQ

Vous venez d'utiliser toutes les fonctionnalités clés de MQTT sur le serveur MQTT public gratuit. Quand vous serez prêt pour des topics privés et de vrais appareils, créez un broker gratuit sur app.connectmq.com. Le plan Serverless gratuit ne demande aucune carte bancaire, prend en charge MQTT 3.1.1 et 5.0 sur TCP, TLS et WebSocket, et vous offre jusqu'à 25 connexions pour construire votre premier projet. Vos identifiants ConnectMQ s'insèrent directement dans le code ci-dessus.

Questions fréquentes

MQTT est-il difficile à apprendre ?

Non. Le modèle de base se limite à des clients, un broker, des topics et le publish/subscribe, et vous pouvez envoyer votre premier message en moins de cinq minutes avec la CLI. La profondeur vient ensuite, avec les sessions, les compromis de QoS et la conception des topics.

Faut-il installer un broker pour suivre ce tutoriel MQTT ?

Non. Chaque étape s'exécute sur broker.connectmq.com, qui accepte les connexions anonymes. Il vous suffit des outils clients Mosquitto, de Python ou d'un navigateur.

Faut-il apprendre MQTT 3.1.1 ou MQTT 5 ?

Apprenez les concepts une fois : ce sont les mêmes dans les deux versions. Utilisez MQTT 5 pour les nouveaux projets, car il ajoute les reason codes, l'expiration des messages, les abonnements partagés et les user properties, tout en restant compatible avec les brokers qui prennent en charge les deux versions.

Le serveur MQTT public gratuit est-il sûr pour des données réelles ?

Non. Tout ce qui se trouve dans l'espace public peut être lu par n'importe qui ; utilisez-le donc uniquement pour des tests et des démos. Les données réelles ont leur place sur un broker privé avec identifiants et TLS.

Que construire après ce tutoriel ?

Connectez un vrai capteur avec un ESP32 ou un Raspberry Pi, stockez les mesures dans une base de données avec un petit script abonné, et construisez un tableau de bord via WebSocket. Chacune de ces étapes réutilise exactement ce que vous avez appris ici.