Ces exemples mosquitto_pub et mosquitto_sub sont les commandes que vous utiliserez réellement pour tester des appareils, déboguer des topics et scripter MQTT. Chacune est prête à copier-coller et s'exécute sur le serveur MQTT public gratuit broker.connectmq.com : vous pouvez donc vérifier le comportement vous-même en quelques secondes. À la fin, vous saurez manipuler la QoS, les retained messages, le Last Will, TLS et les propriétés MQTT 5 depuis la ligne de commande.
Avant de commencer
Installez les clients Mosquitto :
# Debian / Ubuntu / Raspberry Pi OS
sudo apt install mosquitto-clients
# macOS
brew install mosquitto
# Windows: install Mosquitto from mosquitto.org; the installer includes mosquitto_pub.exe and mosquitto_sub.exe
Vérifiez avec mosquitto_pub --help ; la première ligne indique la version. Plusieurs exemples ci-dessous nécessitent la version 2.x (pour -x, la sortie %j et certaines options MQTT 5). La référence complète des options se trouve dans le manuel officiel de mosquitto_pub.
Trois règles pour le broker public :
- Passez toujours un client ID unique et non vide avec
-i. Deux clients avec le même ID se déconnectent mutuellement. - Utilisez un préfixe de topic unique. Les exemples utilisent
connectmq/demo/x7q2/; remplacezx7q2par votre propre chaîne aléatoire. - L'espace public est lisible par tous. Ne publiez jamais d'identifiants ni de données personnelles.
Pour raccourcir les commandes, définissez deux variables shell (bash/zsh) :
H="-h broker.connectmq.com -p 1883"
T="connectmq/demo/x7q2"
Ouvrez deux terminaux : un pour mosquitto_sub, un pour mosquitto_pub.
Exemples de base mosquitto_pub et mosquitto_sub
1. S'abonner à un topic
mosquitto_sub $H -i sub-x7q2 -t "$T/hello"
2. Publier un message
mosquitto_pub $H -i pub-x7q2 -t "$T/hello" -m "hello from the CLI"
3. S'abonner à tout ce qui se trouve sous votre préfixe et afficher les topics (-v affiche le topic avant le payload)
mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v
4. Wildcard à un niveau : tous les topics de température, quelle que soit la pièce
mosquitto_sub $H -i sub-x7q2 -t "$T/+/temperature" -v
5. Plusieurs filtres de topic dans un même client
mosquitto_sub $H -i sub-x7q2 -t "$T/+/temperature" -t "$T/+/humidity" -v
6. Publier du JSON (les guillemets simples empêchent le shell d'interpréter les accolades et les guillemets)
mosquitto_pub $H -i pub-x7q2 -t "$T/kitchen/temperature" -m '{"value": 21.8, "unit": "C"}'
Sous Windows cmd.exe, échappez plutôt les guillemets internes : -m "{\"value\": 21.8}".
QoS et sessions
7. Publier et s'abonner en QoS 1
mosquitto_sub $H -i sub-x7q2 -t "$T/alarms" -q 1 -v
mosquitto_pub $H -i pub-x7q2 -t "$T/alarms" -q 1 -m "door open"
La QoS effective est la plus basse entre la QoS de publication et celle de l'abonnement. Pour une vue complète, consultez les niveaux de QoS MQTT expliqués.
8. Observer l'échange protocolaire avec -d (le mode debug affiche CONNECT, PUBLISH, PUBACK et compagnie)
mosquitto_pub $H -i pub-x7q2 -t "$T/alarms" -q 2 -m "test" -d
Vous verrez PUBLISH, PUBREC, PUBREL et PUBCOMP pour la QoS 2. C'est le moyen le plus rapide de prouver ce que fait réellement un broker.
9. Session persistante : recevoir les messages publiés pendant votre absence
# Subscribe once with a fixed ID, clean session disabled, then Ctrl+C
mosquitto_sub $H -i sub-persist-x7q2 -c -q 1 -t "$T/queue" -v
# While it is stopped, publish at QoS 1
mosquitto_pub $H -i pub-x7q2 -q 1 -t "$T/queue" -m "queued while offline"
# Reconnect with the same ID and -c: the message is delivered
mosquitto_sub $H -i sub-persist-x7q2 -c -q 1 -t "$T/queue" -v
10. Expiration de session MQTT 5 (conserver la session 300 secondes après la déconnexion)
mosquitto_sub $H -V 5 -i sub-persist-x7q2 -c -x 300 -q 1 -t "$T/queue" -v
Le broker public conserve les sessions au maximum 30 minutes.
Retained messages
11. Publier un état retained
mosquitto_pub $H -i pub-x7q2 -t "$T/pump1/state" -r -m "running"
Tout nouveau subscriber reçoit running immédiatement, sans attendre la publication suivante.
12. Afficher uniquement les retained messages, puis quitter
mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v --retained-only -W 3
-W 3 quitte au bout de 3 secondes, pratique pour les scripts qui capturent l'état courant.
13. Ignorer les anciens retained messages (-R ignore les messages qui arrivent avec le flag retain)
mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v -R
14. Supprimer un retained message (publier un payload retained vide)
mosquitto_pub $H -i pub-x7q2 -t "$T/pump1/state" -r -n
15. Effacer tous les retained messages sous votre préfixe
mosquitto_sub $H -i cleaner-x7q2 -t "$T/#" --remove-retained --retained-only -W 3
Utilisez cette commande avec prudence sur n'importe quel broker : elle supprime l'état retained de tout ce que le filtre couvre.
Last Will and Testament
16. Enregistrer un Last Will qui marque le client hors ligne
mosquitto_sub $H -i device-x7q2 -t "$T/device1/cmd" \
--will-topic "$T/device1/status" --will-payload "offline" --will-retain --will-qos 1
Dans un autre terminal, surveillez le statut avec mosquitto_sub $H -i watch-x7q2 -t "$T/device1/status" -v, puis tuez brutalement le premier processus (fermez le terminal ou kill -9). Une fois le keep-alive expiré, le broker publie offline. Un Ctrl+C propre envoie DISCONNECT et ne déclenche pas le Will. Définissez un keep-alive court avec -k 10 pour le constater plus vite.
Scripts et contrôle de la sortie
17. Recevoir exactement N messages, puis quitter
mosquitto_sub $H -i sub-x7q2 -t "$T/kitchen/temperature" -C 1
Idéal dans les scripts shell : TEMP=$(mosquitto_sub ... -C 1).
18. Format de sortie personnalisé avec horodatage
mosquitto_sub $H -i sub-x7q2 -t "$T/#" -F "@Y-@m-@dT@H:@M:@S %t %p"
19. Sortie JSON à rediriger vers jq
mosquitto_sub $H -i sub-x7q2 -t "$T/#" -F "%j" | jq -c '{topic, payload}'
20. Publier chaque ligne d'un fichier ou de stdin comme message distinct
printf '20.1\n20.4\n20.9\n' | mosquitto_pub $H -i pub-x7q2 -t "$T/kitchen/temperature" -l
Utilisez -f firmware.bin pour envoyer un fichier entier en un seul message, ou -s pour envoyer tout stdin en un seul message. Le broker public limite les messages à 64 Ko.
21. Un mini simulateur de capteur (respectez la limite publique de 10 messages par seconde par client)
while true; do
mosquitto_pub $H -i sim-x7q2 -t "$T/lab/temperature" \
-m "{\"value\": $((RANDOM % 10 + 20)), \"ts\": $(date +%s)}"
sleep 1
done
TLS et authentification
22. Connexion chiffrée sur le port 8883
# Linux: use the system CA bundle
mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
-i tls-x7q2 -t "$T/#" -v
Sous macOS ou Windows, pointez --cafile vers un fichier PEM contenant le certificat ISRG Root X1 (Let's Encrypt), car ces systèmes n'exposent pas de répertoire PEM. Si vous voyez Error: A TLS error occurred, vérifiez le chemin du fichier CA et l'horloge de votre système.
23. Broker privé avec identifiants
mosquitto_pub -h YOUR_BROKER_HOST -p 8883 --capath /etc/ssl/certs \
-i YOUR_CLIENT_ID -u YOUR_USERNAME -P YOUR_PASSWORD \
-t "factory1/line1/cnc1/telemetry" -q 1 -m '{"spindle_rpm": 8000}'
Évitez de laisser des mots de passe dans l'historique du shell sur des environnements partagés. Mosquitto 2.x lit ses options depuis un fichier de configuration : placez les lignes -u et -P dans ~/.config/mosquitto_pub (et mosquitto_sub) avec des permissions restrictives.
Propriétés MQTT 5
24. Content type, user property et expiration du message
mosquitto_pub $H -V 5 -i pub-x7q2 -t "$T/kitchen/temperature" -m '{"value": 22}' \
-D PUBLISH content-type application/json \
-D PUBLISH user-property source cli-test \
-D PUBLISH message-expiry-interval 60
Affichez les propriétés côté subscriber avec -V 5 -F "%t %p | %P" (%P affiche les user properties). Le guide des fonctionnalités de MQTT 5 explique dans quels cas chaque propriété est utile.
25. Requête/réponse avec mosquitto_rr
# Responder: read the response topic (%R) of each request and answer it
while true; do
RT=$(mosquitto_sub $H -V 5 -i resp-x7q2 -t "$T/rpc/time" -C 1 -F "%R")
mosquitto_pub $H -V 5 -i resp-pub-x7q2 -t "$RT" -m "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
done &
# Requester: sets the response topic, waits for one reply and prints it
mosquitto_rr $H -V 5 -i req-x7q2 -t "$T/rpc/time" -e "$T/rpc/time/reply" -m "now?" -W 5
mosquitto_rr définit le response topic MQTT 5 sur la requête, s'y abonne et affiche la première réponse. Le répondeur shell suffit pour une démo ; un vrai service en Python ou Node renverrait aussi les correlation data afin de faire correspondre les requêtes simultanées.
Référence rapide des options
| Option | Outil | Signification |
|---|---|---|
-h, -p |
les deux | Hôte et port (1883 TCP, 8883 TLS) |
-i |
les deux | Client ID (à toujours définir) |
-t, -m |
les deux / pub | Topic, message |
-q |
les deux | QoS 0, 1 ou 2 |
-r, -n |
pub | Flag retain, payload nul (vide) |
-c, -x |
sub | Désactive la clean session, expiration de session (MQTT 5) |
-v, -F |
sub | Affiche le topic, format personnalisé |
-C, -W |
sub | Quitte après N messages, délai en secondes |
-R, --retained-only, --remove-retained |
sub | Gestion des retained messages |
-V 5, -D |
les deux | MQTT 5 et propriétés |
-d |
les deux | Sortie de débogage du protocole |
-k |
les deux | Keep-alive en secondes |
Dépannage
Connection Refused: identifier rejected: client ID vide ou invalide. Passez-iavec une valeur unique.- La connexion tombe juste après s'être établie : un autre processus utilise le même client ID.
Error: Connection refusedsur le port 8883 : vous avez oublié--capathou--cafile, et le client a tenté du TCP en clair sur un port TLS.- Rien n'arrive : comparez caractère par caractère le filtre d'abonnement et le topic de publication ; les topics MQTT sont sensibles à la casse et un
/initial crée un niveau vide supplémentaire. - Les messages s'arrêtent après une rafale : limites du broker public (10 messages par seconde par client, 10 abonnements par client, 8 niveaux de topic).
Des tests à la production
Le serveur MQTT public gratuit est parfait pour apprendre ces commandes, mais les appareils sur le terrain ont besoin d'identifiants privés et d'isolation. Un broker MQTT managé de ConnectMQ vous offre TLS sur 8883, WebSocket sur 8083 et 8084, MQTT 3.1.1 et 5.0, et des identifiants générés par broker ; toutes les commandes ci-dessus fonctionnent en reprenant les options de l'exemple 23. Pour d'autres options en ligne de commande, lisez le comparatif des outils CLI MQTT, et si vous préférez une interface graphique, consultez les applications desktop d'exploration MQTT. Le guide des bibliothèques client MQTT montre comment transposer ces tests dans du code.
Démarrer avec ConnectMQ
Créez un broker privé sur app.connectmq.com avec le plan Serverless gratuit, sans carte bancaire. Copiez le nom d'utilisateur, le mot de passe et le client ID générés dans les exemples 22 et 23, et utilisez l'explorateur de topics en direct du portail en parallèle de mosquitto_sub pour confirmer chaque message.
Questions fréquentes
Pourquoi mosquitto_sub n'affiche-t-il rien quand je publie ?
Le plus souvent, le filtre de topic ne correspond pas : vérifiez la casse, les slashs et les wildcards. Assurez-vous aussi que les deux clients utilisent des client ID différents, et ajoutez -d pour voir si l'abonnement a été accordé.
Comment envoyer un message sans payload avec mosquitto_pub ?
Utilisez -n. Combiné à -r, il supprime le retained message de ce topic.
mosquitto_pub peut-il utiliser MQTT 5 ?
Oui, à partir de Mosquitto 1.6. Ajoutez -V 5 (ou -V mqttv5) et définissez les propriétés avec -D <command> <property> <value>.
Faut-il installer le broker Mosquitto pour utiliser ces commandes ?
Non. Le package mosquitto-clients ne contient que les clients en ligne de commande, et ils fonctionnent avec n'importe quel broker MQTT, y compris ConnectMQ.
