Formato da URL do Broker MQTT: mqtt://, mqtts://, ws:// e wss:// Explicados

A URL de um broker MQTT informa ao cliente qual transporte usar, qual host acessar, qual porta abrir e, no caso de WebSockets, qual path solicitar. Ao final deste guia você será capaz de ler e escrever qualquer URL MQTT, escolher o esquema e a porta certos para o seu ambiente e evitar o punhado de erros que causa a maioria dos relatos de "não consigo conectar".

Anatomia da URL de um Broker MQTT

Uma URL MQTT completa tem esta aparência:

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

• Esquema (scheme) seleciona o transporte: TCP puro ou WebSocket, sem ou com criptografia.
• Host é o nome DNS ou o endereço IP do broker.
• Porta (port) é onde o broker escuta para aquele transporte.
• Path só se aplica aos esquemas WebSocket; é o path HTTP para onde vai a requisição de upgrade do WebSocket.

Credenciais e client ID normalmente não fazem parte da URL. Algumas bibliotecas aceitam mqtt://user:pass@host, mas passá-los como opções separadas é mais claro e evita vazar senhas em logs.

Os Quatro Esquemas

Você também pode ver tcp:// e ssl:// em clientes Java e Eclipse Paho; eles equivalem a mqtt:// e mqtts://. Algumas ferramentas também aceitam tls:// para a variante TCP criptografada.

As portas 1883 e 8883 são registradas na IANA para MQTT. As portas WebSocket não são padronizadas, e é por isso que você sempre precisa conferi-las na documentação do broker. Nosso guia de portas MQTT cobre o histórico em mais detalhes.

Escolhendo o Esquema Certo

• Dispositivos e servidores: use mqtts:// na 8883. É a opção criptografada mais eficiente.
• Navegadores: eles não conseguem abrir sockets TCP puros, então precisam usar wss://. Páginas servidas via HTTPS recusam ws:// como conteúdo misto. Veja MQTT sobre WebSocket.
• Redes corporativas restritivas: se a saída na 8883 estiver bloqueada, o wss:// às vezes passa por proxies que entendem WebSockets.
• Testes locais: mqtt:// na 1883 serve em uma rede de laboratório ou com o servidor MQTT público, nunca para credenciais pela internet.

O Path do WebSocket Importa

O erro mais comum com WebSocket é um path ausente ou errado. Os brokers servem MQTT sobre WebSocket em um path HTTP específico, e /mqtt é a convenção mais difundida. A ConnectMQ usa /mqtt tanto na 8083 quanto na 8084. Se você conectar a wss://broker.connectmq.com:8084 sem o path, a requisição de upgrade vai para / e falha, geralmente com um evento de close pouco útil.

Exemplos de URL de Broker MQTT por Cliente

Node.js e Navegadores com MQTT.js

O MQTT.js recebe uma URL e um objeto de opções. Isso funciona no Node.js com mqtts:// e nos navegadores com 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 com paho-mqtt

O Paho não interpreta URLs; ele recebe host, porta e transporte separadamente. Uma pequena função auxiliar converte uma URL nessas partes.

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()

Linha de Comando

As ferramentas do Mosquitto recebem host e porta, não URLs, embora versões mais recentes também aceitem -L com uma URL:

# TCP simples contra o broker público
mosquitto_sub -h broker.connectmq.com -p 1883 -i cli-sub-r4t9 -t 'connectmq/demo/r4t9/#' -v

# TLS com credenciais, usando o formato de URL
mosquitto_sub -L mqtts://YOUR_USERNAME:YOUR_PASSWORD@broker.connectmq.com:8883/devices/# \
  -i YOUR_CLIENT_ID --capath /etc/ssl/certs -v

Com -L, o segmento de path após a porta é o topic, não um path de WebSocket.

Arduino e ESP32

Bibliotecas embarcadas como a PubSubClient também recebem host e porta separadamente. Se a conexão é criptografada ou não depende do cliente de rede, WiFiClient para a 1883 ou WiFiClientSecure para a 8883, e não de um esquema de URL. O tutorial de broker MQTT na nuvem com ESP32 mostra a configuração TLS completa.

Node-RED

No nó de configuração mqtt-broker, defina Server como broker.connectmq.com, Port como 1883 ou 8883 e marque "Use TLS" para a 8883. Para WebSockets, digite a URL completa wss://broker.connectmq.com:8084/mqtt no campo Server.

Checklist de Solução de Problemas

Quando uma conexão falhar, verifique estes itens na ordem:

1. Esquema e porta são compatíveis. mqtts:// na 1883 ou mqtt:// na 8883 vão falhar ou travar.
2. O path do WebSocket está presente. /mqtt no broker.connectmq.com.
3. Hostname, e não IP, para TLS. O certificado é emitido para o hostname; conectar pelo IP falha na validação.
4. Nada de ws:// a partir de páginas HTTPS. Os navegadores bloqueiam como conteúdo misto.
5. O firewall libera a porta. Redes corporativas costumam bloquear a saída nas portas 1883 e 8883.
6. O client ID não está vazio e é único. Duplicatas causam loops de desconexão.
7. As credenciais ficam separadas da URL, a menos que a biblioteca documente credenciais na URL, e, nesse caso, caracteres especiais devem ser codificados para URL.
8. O repositório de CAs do cliente confia no certificado do servidor. O broker.connectmq.com usa um certificado Let's Encrypt, no qual os repositórios padrão dos sistemas confiam.

Guardando a URL do Broker na Configuração

Fixar uma URL no código-fonte é o caminho mais rápido para tornar as mudanças de ambiente dolorosas. Mantenha a URL completa, as credenciais e o client ID na configuração, para que o mesmo código possa apontar para o servidor MQTT público durante o desenvolvimento, para um broker privado em staging e para um endpoint dedicado em produção.

Um layout simples com variáveis de ambiente funciona para a maioria dos serviços:

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"

Depois, leia-as na inicialização, por exemplo mqtt.connect(process.env.MQTT_URL, { clientId: process.env.MQTT_CLIENT_ID, username: process.env.MQTT_USERNAME, password: process.env.MQTT_PASSWORD }) no Node.js, ou a função auxiliar client_from_url acima no Python. Alguns hábitos tornam isso robusto:

• Valide na inicialização. Rejeite um esquema desconhecido ou uma URL WebSocket sem path antes de tentar conectar e registre o esquema, o host e a porta (nunca a senha), para que um erro de configuração fique evidente.
• Mantenha os segredos separados da URL. Guarde a senha no seu gerenciador de segredos e a URL na configuração comum; assim, a URL pode aparecer com segurança em logs e dashboards.
• Use uma variável por ambiente, não por transporte. Se um build para navegador precisa de wss:// enquanto um backend usa mqtts://, dê a cada artefato implantável sua própria configuração em vez de derivar uma da outra com substituição de strings.
• Documente o formato esperado. Um comentário de uma linha, como scheme://host:port[/path], ao lado da configuração poupa o próximo desenvolvedor de adivinhar.

URLs Públicas vs Privadas

O hostname é o mesmo para o servidor MQTT público e para os brokers privados, o que mantém os exemplos simples. No servidor MQTT público (gratuito), você se conecta anonimamente com qualquer client ID único e um prefixo de topic exclusivo, como connectmq/demo/r4t9/...; tudo ali pode ser lido por qualquer pessoa, então ele serve para testes e protótipos, não para dados de produção. Um broker privado da ConnectMQ usa a mesma URL com o username, a senha e o client ID gerados para você, e o seu tráfego fica no seu próprio tenant isolado. Para o panorama geral das opções de hospedagem, veja o guia de broker MQTT na nuvem e nossa visão geral sobre o que um broker MQTT faz.

Obtenha a URL do Seu Próprio Broker na ConnectMQ

Crie um broker MQTT gerenciado Serverless gratuito em app.connectmq.com, sem cartão de crédito. O portal mostra seus endpoints para os quatro esquemas junto com as credenciais geradas, e o cliente no navegador permite testar uma conexão wss:// na hora. A ConnectMQ suporta MQTT 3.1.1 e 5.0 em todos os endpoints.

Perguntas frequentes

Qual é a diferença entre mqtt:// e mqtts://?

mqtt:// é TCP simples, geralmente na porta 1883. mqtts:// envolve o mesmo protocolo em TLS, geralmente na porta 8883, criptografando credenciais e payloads.

Por que minha conexão wss:// falha sem mensagem de erro?

A causa mais comum é a ausência do path do WebSocket. Adicione /mqtt à URL e confirme que a porta é a de WebSocket seguro, 8084 na ConnectMQ.

Posso colocar o username e a senha na URL MQTT?

Algumas bibliotecas suportam scheme://user:pass@host:port, mas opções separadas são mais seguras e evitam vazar segredos em logs.

tcp:// é o mesmo que mqtt://?

Sim. Clientes Java e Paho usam tcp:// e ssl://, que correspondem a mqtt:// e mqtts://.