Format de l'URL d'un broker MQTT : mqtt://, mqtts://, ws:// et wss:// expliqués

L'URL d'un broker MQTT indique au client quel transport utiliser, quel hôte joindre, quel port ouvrir et, pour les WebSockets, quel chemin demander. À la fin de ce guide, vous saurez lire et écrire n'importe quelle URL MQTT, choisir le bon schéma et le bon port pour votre environnement, et éviter la poignée d'erreurs à l'origine de la plupart des signalements « impossible de se connecter ».

Anatomie de l'URL d'un broker MQTT

Une URL MQTT complète ressemble à ceci :

wss://broker.connectmq.com:8084/mqtt
\_/   \__________________/ \__/\___/
 |            |              |    |
scheme       host           port path

• Le schéma sélectionne le transport : TCP brut ou WebSocket, en clair ou chiffré.
• L'hôte est le nom DNS ou l'adresse IP du broker.
• Le port est celui sur lequel le broker écoute pour ce transport.
• Le chemin ne s'applique qu'aux schémas WebSocket ; c'est le chemin HTTP vers lequel est envoyée la requête d'upgrade WebSocket.

Les identifiants et le client ID ne font généralement pas partie de l'URL. Certaines bibliothèques acceptent mqtt://user:pass@host, mais les passer sous forme d'options séparées est plus clair et évite que des mots de passe se retrouvent dans les journaux.

Les quatre schémas

Vous verrez aussi tcp:// et ssl:// dans les clients Java et Eclipse Paho ; ils équivalent à mqtt:// et mqtts://. Certains outils acceptent également tls:// pour la variante TCP chiffrée.

Les ports 1883 et 8883 sont enregistrés auprès de l'IANA pour MQTT. Les ports WebSocket ne sont pas standardisés : c'est pourquoi vous devez toujours les vérifier dans la documentation du broker. Notre guide des ports MQTT revient plus en détail sur leur historique.

Choisir le bon schéma

• Appareils et serveurs : utilisez mqtts:// sur 8883. C'est l'option chiffrée la plus efficace.
• Navigateurs : ils ne peuvent pas ouvrir de sockets TCP bruts et doivent donc utiliser wss://. Les pages servies en HTTPS refusent ws:// comme contenu mixte. Voir MQTT over WebSocket.
• Réseaux d'entreprise restrictifs : si le port 8883 sortant est bloqué, wss:// passe parfois à travers les proxys qui gèrent les WebSockets.
• Tests en local : mqtt:// sur 1883 convient sur un réseau de labo ou avec le serveur MQTT public gratuit, jamais pour transmettre des identifiants sur Internet.

Le chemin WebSocket compte

L'erreur WebSocket la plus fréquente est un chemin absent ou incorrect. Les brokers servent MQTT over WebSocket sur un chemin HTTP précis, et /mqtt est la convention la plus répandue. ConnectMQ utilise /mqtt sur 8083 comme sur 8084. Si vous vous connectez à wss://broker.connectmq.com:8084 sans le chemin, la requête d'upgrade part vers / et échoue, généralement avec un événement de fermeture peu explicite.

Exemples d'URL de broker MQTT par client

Node.js et navigateurs avec MQTT.js

MQTT.js prend une URL plus un objet d'options. Ce code fonctionne dans Node.js avec mqtts:// et dans les navigateurs avec wss://.

import mqtt from "mqtt";

const isBrowser = typeof window !== "undefined";
const url = isBrowser
  ? "wss://broker.connectmq.com:8084/mqtt"
  : "mqtts://broker.connectmq.com:8883";

const client = mqtt.connect(url, {
  clientId: "YOUR_CLIENT_ID",
  username: "YOUR_USERNAME",
  password: "YOUR_PASSWORD",
  protocolVersion: 5,
  keepalive: 60,
  reconnectPeriod: 2000,
});

client.on("connect", () => {
  console.log("Connected to", url);
  client.subscribe("demo/#", { qos: 1 });
  client.publish("demo/hello", "hi from MQTT.js", { qos: 1 });
});

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

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

Python avec paho-mqtt

Paho n'analyse pas les URL ; il prend l'hôte, le port et le transport séparément. Une petite fonction utilitaire convertit une URL en ces différents éléments.

import ssl
from urllib.parse import urlparse

import paho.mqtt.client as mqtt

DEFAULT_PORTS = {"mqtt": 1883, "mqtts": 8883, "ws": 8083, "wss": 8084}


def client_from_url(url: str, client_id: str, username=None, password=None):
    u = urlparse(url)
    scheme = u.scheme.lower()
    transport = "websockets" if scheme in ("ws", "wss") else "tcp"
    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id,
                         transport=transport, protocol=mqtt.MQTTv5)
    if transport == "websockets":
        client.ws_set_options(path=u.path or "/mqtt")
    if scheme in ("mqtts", "wss"):
        client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
    if username:
        client.username_pw_set(username, password)
    port = u.port or DEFAULT_PORTS[scheme]
    return client, u.hostname, port


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)


client, host, port = client_from_url(
    "wss://broker.connectmq.com:8084/mqtt",
    client_id="YOUR_CLIENT_ID",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.on_connect = on_connect
client.connect(host, port, keepalive=60)
client.loop_forever()

En ligne de commande

Les outils Mosquitto prennent un hôte et un port, pas des URL, mais les versions récentes acceptent aussi -L avec une URL :

# TCP en clair vers le broker public
mosquitto_sub -h broker.connectmq.com -p 1883 -i cli-sub-r4t9 -t 'connectmq/demo/r4t9/#' -v

# TLS avec identifiants, sous forme d'URL
mosquitto_sub -L mqtts://YOUR_USERNAME:YOUR_PASSWORD@broker.connectmq.com:8883/devices/# \
  -i YOUR_CLIENT_ID --capath /etc/ssl/certs -v

Avec -L, le segment de chemin après le port est le topic, pas un chemin WebSocket.

Arduino et ESP32

Les bibliothèques embarquées comme PubSubClient prennent elles aussi l'hôte et le port séparément. Le chiffrement de la connexion dépend du client réseau, WiFiClient pour 1883 ou WiFiClientSecure pour 8883, et non d'un schéma d'URL. Le tutoriel broker MQTT cloud ESP32 montre la configuration TLS complète.

Node-RED

Dans le nœud de configuration mqtt-broker, renseignez Server avec broker.connectmq.com, Port avec 1883 ou 8883, et cochez « Use TLS » pour 8883. Pour les WebSockets, saisissez plutôt l'URL complète wss://broker.connectmq.com:8084/mqtt dans le champ Server.

Checklist de dépannage

Quand une connexion échoue, vérifiez ces points dans l'ordre :

1. Le schéma et le port concordent. mqtts:// sur 1883 ou mqtt:// sur 8883 échouera ou restera bloqué.
2. Le chemin WebSocket est présent. /mqtt sur broker.connectmq.com.
3. Un nom d'hôte, pas une IP, pour le TLS. Le certificat est émis pour le nom d'hôte ; une connexion par IP échoue à la validation.
4. Pas de ws:// depuis des pages HTTPS. Les navigateurs le bloquent comme contenu mixte.
5. Le pare-feu autorise le port. Les réseaux d'entreprise bloquent souvent 1883 et 8883 en sortie.
6. Le client ID est non vide et unique. Les doublons provoquent des boucles de déconnexion.
7. Les identifiants sont séparés de l'URL, sauf si la bibliothèque documente les identifiants dans l'URL, auquel cas les caractères spéciaux doivent être encodés.
8. Le magasin de CA du client fait confiance au certificat du serveur. broker.connectmq.com utilise un certificat Let's Encrypt, reconnu par les magasins système standard.

Stocker l'URL du broker dans la configuration

Coder une URL en dur dans le source est le moyen le plus sûr de rendre pénibles les changements d'environnement. Gardez l'URL complète, ainsi que les identifiants et le client ID, dans la configuration, pour que le même code puisse pointer vers le serveur MQTT public gratuit en développement, vers un broker privé en préproduction et vers un endpoint dédié en production.

Une simple organisation en variables d'environnement convient à la plupart des services :

export MQTT_URL="mqtts://broker.connectmq.com:8883"
export MQTT_USERNAME="YOUR_USERNAME"
export MQTT_PASSWORD="YOUR_PASSWORD"
export MQTT_CLIENT_ID="YOUR_CLIENT_ID"

Lisez-les ensuite au démarrage, par exemple avec mqtt.connect(process.env.MQTT_URL, { clientId: process.env.MQTT_CLIENT_ID, username: process.env.MQTT_USERNAME, password: process.env.MQTT_PASSWORD }) en Node.js, ou avec la fonction client_from_url ci-dessus en Python. Quelques habitudes rendent ce dispositif robuste :

• Validez au démarrage. Rejetez un schéma inconnu ou une URL WebSocket sans chemin avant de tenter la connexion, et journalisez le schéma, l'hôte et le port (jamais le mot de passe) pour qu'une erreur de configuration saute aux yeux.
• Séparez les secrets de l'URL. Stockez le mot de passe dans votre gestionnaire de secrets et l'URL dans la configuration ordinaire ; l'URL peut alors apparaître sans risque dans les journaux et les tableaux de bord.
• Une variable par environnement, pas par transport. Si un build navigateur a besoin de wss:// alors qu'un backend utilise mqtts://, donnez à chaque livrable son propre paramètre plutôt que de dériver l'un de l'autre par remplacement de chaîne.
• Documentez le format attendu. Un commentaire d'une ligne comme scheme://host:port[/path] à côté du paramètre évite au développeur suivant de deviner.

URL publiques et privées

Le nom d'hôte est le même pour le serveur MQTT public gratuit et pour les brokers privés, ce qui simplifie les exemples. Sur le serveur MQTT public gratuit, réservé aux tests et aux prototypes, vous vous connectez anonymement avec n'importe quel client ID unique et un préfixe de topic unique comme connectmq/demo/r4t9/... ; tout y est lisible par le monde entier. Un broker MQTT managé ConnectMQ privé utilise la même URL avec vos nom d'utilisateur, mot de passe et client ID générés, et votre trafic reste dans votre propre espace client isolé. Pour une vue d'ensemble des choix d'hébergement, consultez le guide du broker MQTT cloud et notre présentation de ce que fait un broker MQTT.

Obtenez votre propre URL de broker sur ConnectMQ

Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire. Le portail affiche vos endpoints pour les quatre schémas ainsi que les identifiants générés, et son client intégré au navigateur vous permet de tester immédiatement une connexion wss://. ConnectMQ prend en charge MQTT 3.1.1 et 5.0 sur chaque endpoint.

Questions fréquentes

Quelle est la différence entre mqtt:// et mqtts:// ?

mqtt:// désigne du TCP en clair, généralement sur le port 1883. mqtts:// encapsule le même protocole dans TLS, généralement sur le port 8883, ce qui chiffre les identifiants et les payloads.

Pourquoi ma connexion wss:// échoue-t-elle sans message d'erreur ?

La cause la plus fréquente est l'absence du chemin WebSocket. Ajoutez /mqtt à l'URL et vérifiez que le port est bien le port WebSocket sécurisé, 8084 sur ConnectMQ.

Puis-je mettre le nom d'utilisateur et le mot de passe dans l'URL MQTT ?

Certaines bibliothèques acceptent scheme://user:pass@host:port, mais des options séparées sont plus sûres et évitent que des secrets fuitent dans les journaux.

tcp:// est-il la même chose que mqtt:// ?

Oui. Les clients Java et Paho utilisent tcp:// et ssl://, qui correspondent à mqtt:// et mqtts://.