Extensão MQTT para VS Code: Publique e Assine sem Sair do Editor

Uma extensão MQTT para VS Code acaba com a troca constante de janelas no desenvolvimento IoT: o firmware em uma janela, um cliente desktop em outra, um terminal em algum lugar atrás das duas. Neste guia você vai configurar o MQTT dentro do Visual Studio Code com a extensão ConnectMQ, organizar payloads de teste como arquivos no seu repositório e adicionar tarefas de workspace que executam verificações CLI repetíveis. Tudo é demonstrado no servidor MQTT público (gratuito) broker.connectmq.com.

Por que trazer o MQTT para o editor

Quando você muda o nome de um topic no código, quer ver o efeito na hora. Quando corrige um campo JSON, quer publicar um payload de teste que exercite a correção. Fazer isso dentro do editor traz benefícios concretos:

• Ciclo de feedback mais curto. Edite, grave o firmware ou reinicie, e acompanhe o topic em um painel ao lado do código.
• Os payloads vivem junto com o código. As mensagens de teste viram arquivos versionados que os colegas podem reutilizar e revisar.
• Menos ferramentas para instalar. Novos membros da equipe instalam a extensão e as tarefas do workspace e já estão prontos.
• Configurações de conexão consistentes. Todos testam com as mesmas configurações de broker, o que evita erros de topic do tipo "na minha máquina funciona".

Instalando a extensão ConnectMQ para VS Code

1. Abra a visualização de Extensões (Ctrl+Shift+X, ou Cmd+Shift+X no macOS).
2. Pesquise por ConnectMQ e instale a extensão oficial.
3. Abra a extensão pelo ícone dela ou pela Paleta de Comandos (Ctrl+Shift+P), digitando o nome da extensão.

A extensão permite conectar a brokers MQTT, assinar topics e publicar payloads de teste sem sair do VS Code. Ela funciona com qualquer broker MQTT padrão. Os rótulos exatos podem mudar entre versões; a página da extensão no Marketplace é a referência para a interface atual.

Conectando a um broker

Crie uma conexão com estes valores para o servidor MQTT público:

Escolha um prefixo de topic exclusivo para os seus testes, como connectmq/demo/7hq2/. O servidor MQTT público pode ser lido por qualquer pessoa e serve para testes e protótipos, então nunca publique segredos, dados de produção ou dados reais de clientes ali. Os limites públicos são 64 KB por mensagem, 10 mensagens por segundo por cliente, 10 assinaturas por cliente e até 8 níveis de topic.

Assine e publique pela extensão MQTT para VS Code

Com a conexão aberta:

1. Assine connectmq/demo/7hq2/# para ver tudo o que está sob o seu prefixo.
2. Publique uma mensagem de teste em connectmq/demo/7hq2/device1/cmd com o payload {"action": "blink", "times": 3}.
3. Confirme que ela chega na sua visualização de assinaturas e então aponte o seu dispositivo ou serviço para os mesmos topics.

Manobras típicas de depuração que ficam rápidas dentro do editor:

• Caça a erros de digitação em topics. Assine o pai com # e compare os topics que realmente chegam com as strings do seu código.
• Verificação de estado retido. Reconecte e veja quais topics mostram valor imediatamente; esses são os retidos.
• Teste de comandos. Publique exatamente o comando que o seu app enviaria e acompanhe o topic de resposta do dispositivo.

Mantenha os payloads de teste como arquivos no repositório

Seja qual for o cliente de onde você publica, guarde as mensagens de teste canônicas no repositório. Uma estrutura simples:

mqtt/
  payloads/
    cmd-blink.json
    cmd-reboot.json
    telemetry-normal.json
    telemetry-out-of-range.json
  README.md

Exemplo de mqtt/payloads/telemetry-out-of-range.json:

{
  "deviceId": "device1",
  "temperature": 142.7,
  "humidity": -3,
  "ts": 1760600000000
}

Payloads de casos extremos como este (valores impossíveis, campos ausentes, tipos errados) são justamente os que você vai precisar ao testar a validação no backend. Mantê-los como arquivos permite revisá-los, e o VS Code valida a sintaxe JSON enquanto você digita.

Adicione tarefas de workspace para verificações CLI repetíveis

Uma extensão é ideal para o trabalho interativo. Para verificações repetíveis, tarefas do VS Code que encapsulam mosquitto_pub e mosquitto_sub a complementam bem e rodam no terminal integrado. Crie .vscode/tasks.json:

{
  "version": "2.0.0",
  "inputs": [
    {
      "id": "payloadFile",
      "type": "pickString",
      "description": "Payload to publish",
      "options": [
        "mqtt/payloads/cmd-blink.json",
        "mqtt/payloads/telemetry-normal.json",
        "mqtt/payloads/telemetry-out-of-range.json"
      ]
    }
  ],
  "tasks": [
    {
      "label": "MQTT: watch demo topics",
      "type": "shell",
      "command": "mosquitto_sub -h broker.connectmq.com -p 1883 -i vscode-watch-7hq2 -t 'connectmq/demo/7hq2/#' -v",
      "isBackground": true,
      "problemMatcher": []
    },
    {
      "label": "MQTT: publish payload file",
      "type": "shell",
      "command": "mosquitto_pub -h broker.connectmq.com -p 1883 -i vscode-pub-7hq2 -t connectmq/demo/7hq2/device1/telemetry -q 1 -f ${input:payloadFile}",
      "problemMatcher": []
    },
    {
      "label": "MQTT: wait for one telemetry message",
      "type": "shell",
      "command": "mosquitto_sub -h broker.connectmq.com -p 1883 -i vscode-check-7hq2 -t connectmq/demo/7hq2/device1/telemetry -C 1 -W 15",
      "problemMatcher": []
    }
  ]
}

Execute-as em Terminal > Run Task. O input pickString permite escolher qual arquivo de payload enviar, e -f publica o conteúdo do arquivo como mensagem. A última tarefa termina com erro se nada chegar em 15 segundos, um teste de fumaça prático depois de gravar o firmware. Se precisar de mais variações, veja os exemplos de mosquitto_pub e mosquitto_sub. Essas tarefas exigem os clientes Mosquitto instalados; ferramentas CLI para MQTT compara alternativas caso você prefira outro cliente de linha de comando.

Um fluxo de trabalho prático para firmware

Veja como tudo se encaixa ao desenvolver um dispositivo ESP32 no VS Code com PlatformIO:

1. Inicie a tarefa "watch demo topics" (ou assine pela extensão).
2. Compile e envie o firmware; abra o monitor serial em outro painel.
3. Observe a primeira telemetria do dispositivo e o seu status retido aparecerem.
4. Publique cmd-blink.json no topic de comando e observe o LED e o log serial.
5. Publique telemetry-out-of-range.json no topic de telemetria para verificar como o seu backend lida com dados ruins.

Os cinco passos acontecem sem sair do editor. Para o lado do dispositivo, o tutorial de MQTT com ESP32 traz um firmware compatível com esta estrutura de topics.

Lidando com credenciais com segurança no workspace

Nunca faça commit de senhas do broker em tasks.json ou em arquivos de payload. Dois padrões mais seguros:

• Use variáveis de ambiente nas tarefas: -u $MQTT_USER -P $MQTT_PASS (no Windows PowerShell, $env:MQTT_USER), e defina-as no perfil do seu shell ou em um arquivo .env local excluído pelo .gitignore.
• Mantenha um arquivo de configuração do cliente Mosquitto fora do repositório (~/.config/mosquitto_pub) contendo as linhas -u e -P.

Para um broker privado no ConnectMQ, o portal gera o usuário, a senha e o client ID quando você cria o broker, e os client IDs ficam vinculados a essas credenciais, então use o ID emitido tanto na extensão quanto nas tarefas. Boas práticas de segurança MQTT aborda o tratamento de credenciais para dispositivos e equipes.

Editor, desktop ou navegador?

Indo além do broker público

O servidor MQTT público é ideal para experimentar a extensão, mas o desenvolvimento em equipe e os dispositivos reais precisam de um broker privado e autenticado. Um broker MQTT gerenciado dá a cada desenvolvedor e dispositivo suas próprias credenciais sobre TLS, sem que você precise operar servidores. Quando estiver pronto para escrever o código da aplicação, a visão geral das bibliotecas cliente MQTT mostra as chamadas equivalentes de publish e subscribe em cada uma das principais linguagens.

Comece a usar o ConnectMQ

Instale a extensão ConnectMQ para VS Code e crie um broker privado em app.connectmq.com no plano gratuito Serverless, sem cartão de crédito. Cole as credenciais geradas em uma nova conexão e, em minutos, você estará testando tráfego real de dispositivos direto do seu editor.

Perguntas frequentes

Existe um cliente MQTT nativo no VS Code?

Não. O VS Code não tem suporte nativo a MQTT, então você o adiciona com uma extensão como a descrita aqui, ou com tarefas que executam clientes de linha de comando no terminal integrado.

A extensão ConnectMQ para VS Code funciona com outros brokers?

Sim. Ela se conecta a brokers MQTT padrão e combina naturalmente com brokers criados no portal.

Posso rodar testes MQTT automaticamente a partir do VS Code?

Sim. Tarefas de workspace podem publicar arquivos de payload e aguardar as mensagens esperadas com mosquitto_sub -C 1 -W 15, que faz a tarefa falhar se nada chegar a tempo.

Devo fazer commit do tasks.json com as configurações do broker?

Faça commit de tarefas que usam o servidor MQTT público ou variáveis de ambiente, mas nunca de senhas. Mantenha as credenciais privadas em variáveis de ambiente ou em arquivos de configuração locais excluídos do git.