MQTT Client

Table of contents

• About
• Installation
• Usage
  • Configure Connection to an MQTT Broker
  • Subscribe to a Topic
  • Publish a Message to a Topic
  • Subscribe to a Topic and Save Messages to a JSON File
  • Subscribe to Topics Using Wildcards
• Changelog
  • Release 1.0

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-scoop.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

Release 1.0

• First public release.