Skip to main content

MQTT Client

About​

MQTT Client is a command-line MQTT client for Windows, designed for simplicity, lightweight operation, and ease of automation, making it an excellent alternative to GUI-based MQTT tools.

The primary purpose of this client is to simplify the following tasks:

  • Troubleshoot connectivity and configuration of an MQTT broker;
  • Receive binary and text messages from an MQTT broker;
  • Collect received messages into JSON files for further analysis and processing;
  • Publish text messages to a topic.

Installation​

On Windows, MQTT Client is available as a Scoop package, which automates installation and upgrades.

Using Scoop, installing MQTT Client is as easy as:

> scoop bucket add mqttclient https://github.com/relbis-labs/packages-mqtt-client.git
> scoop install mqttclient

Usage​

Configure Connection to an MQTT Broker​

  1. Create a new configuration file mqtt.config.yaml: 
    > mqttclient create-config
  2. Specify connection parameters in the configuration file: 
    # Server address and port
    Server: mqtt.server.com
    Port: 8883

    # Username and password (optional)
    Username: "my-username"
    Password: "my-password"

    # Enable or disable TLS encryption
    UseTls: True

    # Enable or disable authentication using a client certificate file
    UseClientCertificates: True
    # The file name and password for the client certificate file
    # Required only when UseClientCertificates is set to 'True' 
    ClientCertificateFile: "client-certificate.pfx"
    ClientCertificatePassword: "client-certificate-password"

    # Ignore validation errors for server certificates (optional)
    IgnoreCertificateValidationErrors: False

    # Client ID (optional)
    # If not provided, a randomly generated value is used.
    ClientId: "mqtt-client"

Subscribe to a Topic​

  • Use the subscribe command to subscribe to a topic: 
    > mqttclient subscribe --topic "myhome/groundfloor/livingroom/temperature"
  • The command will start waiting for new messages: 
    MQTT client connected to the server: 'mqtt.server.com:8883'.
    MQTT client subscribed to topic 'myhome/groundfloor/livingroom/temperature'.
    Press Enter to exit.

Publish a Message to a Topic​

  • Use the publish command to send a message to a topic: 
    > mqttclient publish --topic "myhome/groundfloor/livingroom/temperature" --payload '{"value": "21.5C", "timestamp": "2025-03-01T22:57:11"}'
  • The subscribed client will receive the message and display output: 
    Time: 22:58:17
    Topic: myhome/groundfloor/livingroom/temperature
    Payload: {"value": "21.5C", "timestamp": "2025-03-01T22:57:11"}

Subscribe to a Topic and Save Messages to a JSON File​

  • Use the subscribe command with the --output-file-name parameter: 
    > mqttclient subscribe --topic "myhome/groundfloor/livingroom/temperature" --output-file-name "temperature-log.json" --use-unsafe-relaxed-json-escaping
  • The application writes received messages to temperature-log.json. Example: 
    {
      "Topic": "myhome/groundfloor/livingroom/temperature",
      "Payload": {"value": "21.5C", "timestamp": "2025-03-01T22:57:11"},
      "IngestionTime": "2025-03-01T22:57:12.6016321+00:00",
      "Format": "JSON/Document"
    }

Subscribe to Topics Using Wildcards​

The tool allows subscribing to topics using wildcards. Examples:

  • Subscribe to all temperature sensors on the ground floor: 
    > mqttclient subscribe --topic "myhome/groundfloor/+/temperature"
  • Subscribe to all sensors in the home: 
    > mqttclient subscribe --topic "myhome/#"

Changelog​

See Releases

Have a question or suggestion?

There is more than one way to start a conversation: