MQTT Client

Overview

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol originally designed for constrained devices and low-bandwidth networks. It is the protocol of choice for IoT, telemetry, mobile messaging and machine-to-machine communication, and is supported natively by every major IoT cloud (AWS IoT Core, Azure IoT Hub, Google IoT Core), broker (Mosquitto, HiveMQ, EMQX, RabbitMQ) and SDK.

The sgcWebSockets TsgcWSPClient_MQTT component delivers a full MQTT client implementation written in native Delphi, supporting versions 3.1.1 and 5.0, plain-text and TLS-secured transports, and both standard TCP and MQTT-over-WebSocket connections. It plugs into any sgcWebSockets server stack via TsgcWebSocketClient and ships with the WatchDog auto-reconnect, three-level QoS and Last-Will-Testament semantics defined by the OASIS specifications.

At a glance

Features

• Versions 3.1.1 and 5.0 — full coverage of both specifications, including MQTT 5.0 reason codes, properties, topic aliases, session expiry, request/response and shared subscriptions.
• Publish / Subscribe — one-to-many message distribution with topic filters, wildcards (+, #), retained messages and queued deliveries.
• Three QoS levels — at-most-once (fire and forget), at-least-once (PUBACK), exactly-once (4-step PUBREC / PUBREL / PUBCOMP handshake).
• Last Will and Testament — the broker publishes a configured payload to a configured topic when the client disconnects abnormally.
• Authentication — username / password, client certificates, enhanced SASL-style challenge/response (MQTT 5.0).
• Secure connections — TLS 1.2 / 1.3 via OpenSSL or SChannel, mutual TLS, ALPN.
• HeartBeat and WatchDog — keep-alive PING / PINGRESP and automatic reconnect with subscription replay.
• WebSocket transport — MQTT over WebSockets, the standard transport for browser-hosted MQTT and JavaScript-paired clients.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Public events

The component exposes the following published events; these mirror the protocol's packet types and let your application observe each step of the MQTT exchange.

Quick Start

Drop a TsgcWebSocketClient (or TsgcTCPClient) and a TsgcWSPClient_MQTT on a form, set the transport's host / port, point the MQTT component's Client property at the transport, wire the OnMQTTPublish handler, then activate.

Delphi (VCL / FireMonkey)

uses
  sgcWebSocket_Classes,
  sgcWebSocket_Client,
  sgcWebSocket_Protocol_MQTT_Client,
  sgcWebSocket_Protocol_MQTT_Message;

var
  Transport: TsgcWebSocketClient;
  MQTT:      TsgcWSPClient_MQTT;

procedure TForm1.FormCreate(Sender: TObject);
begin
  Transport := TsgcWebSocketClient.Create(Self);
  Transport.Host := 'test.mosquitto.org';
  Transport.Port := 1883;

  MQTT := TsgcWSPClient_MQTT.Create(Self);
  MQTT.Client := Transport;
  MQTT.OnMQTTConnect := MQTTConnect;
  MQTT.OnMQTTPublish := MQTTPublish;

  Transport.Active := True;
end;

procedure TForm1.MQTTConnect(Connection: TsgcWSConnection;
  const Session: Boolean;
  const ReasonCode: Integer;
  const ReasonName: string;
  const ConnectProperties: TsgcWSMQTTCONNACKProperties);
begin
  // connected — subscribe to a topic with QoS 1
  MQTT.Subscribe('sensors/temperature/#', mtqsAtLeastOnce);
end;

procedure TForm1.MQTTPublish(Connection: TsgcWSConnection;
  aTopic, aText: string;
  PublishProperties: TsgcWSMQTTPublishProperties);
begin
  Memo1.Lines.Add('[' + aTopic + '] ' + aText);
end;

procedure TForm1.btnPublishClick(Sender: TObject);
begin
  MQTT.Publish('sensors/temperature/lab-1', '21.4', mtqsAtLeastOnce, False);
end;

C++ Builder

// Drop TsgcWebSocketClient (named Transport) and
// TsgcWSPClient_MQTT (named MQTT) on the form,
// set MQTT->Client = Transport at design time, then:

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  Transport->Host   = "test.mosquitto.org";
  Transport->Port   = 1883;
  Transport->Active = true;
}

void __fastcall TForm1::MQTTMQTTConnect(TsgcWSConnection *Connection,
  const bool Session, const int ReasonCode,
  const UnicodeString ReasonName,
  const TsgcWSMQTTCONNACKProperties &ConnectProperties)
{
  MQTT->Subscribe("sensors/temperature/#", mtqsAtLeastOnce);
}

void __fastcall TForm1::MQTTMQTTPublish(TsgcWSConnection *Connection,
  UnicodeString aTopic, UnicodeString aText,
  TsgcWSMQTTPublishProperties &PublishProperties)
{
  Memo1->Lines->Add("[" + aTopic + "] " + aText);
}

void __fastcall TForm1::btnPublishClick(TObject *Sender)
{
  MQTT->Publish("sensors/temperature/lab-1", "21.4",
                mtqsAtLeastOnce, false);
}

.NET (C#)

using esegece.sgcWebSockets;

public partial class FRMMQTT : Form
{
    private TsgcWebSocketClient Transport;
    private TsgcWSPClient_MQTT  MQTT;

    public FRMMQTT()
    {
        InitializeComponent();

        Transport      = new TsgcWebSocketClient();
        Transport.Host = "test.mosquitto.org";
        Transport.Port = 1883;

        MQTT                       = new TsgcWSPClient_MQTT();
        MQTT.Client                = Transport;
        MQTT.HeartBeat.Enabled     = true;
        MQTT.HeartBeat.Interval    = 5;

        MQTT.OnMQTTConnect += (conn, session, code, name, props) =>
        {
            // connected — subscribe with QoS 1
            MQTT.Subscribe("sensors/temperature/#",
                TmqttQoS.mtqsAtLeastOnce);
        };

        MQTT.OnMQTTPublish += (conn, topic, text, props) =>
        {
            memoLog.AppendText("[" + topic + "] " + text + "\r\n");
        };

        Transport.Active = true;
    }

    private void btnPublishClick(object sender, EventArgs e)
    {
        MQTT.Publish("sensors/temperature/lab-1", "21.4",
                     TmqttQoS.mtqsAtLeastOnce, false);
    }
}

Common scenarios

1 · Subscribe with a topic-filter wildcard

Topic filters use + for a single-level wildcard and # for a multi-level wildcard. The expression devices/+/status matches devices/lab-1/status and devices/lab-2/status but not devices/lab-1/health/cpu; the expression logs/# matches everything starting with logs/.

MQTT.Subscribe('devices/+/status', mtqsAtLeastOnce);
MQTT.Subscribe('logs/#',           mtqsAtMostOnce);

2 · Publish with retained flag and QoS 2

A retained message is stored by the broker and delivered to any new subscriber whose filter matches the topic. QoS 2 guarantees exactly-once delivery via the four-step PUBREC / PUBREL / PUBCOMP handshake.

MQTT.Publish('config/firmware', '1.4.2',
  mtqsExactlyOnce,
  True);  // retained

3 · Last Will and Testament

The broker publishes the configured payload to the configured topic when the connection is closed abnormally (network drop, crash, etc.). Subscribers see the message just as if the publisher had explicitly sent it.

MQTT.LastWill.Enabled := True;
MQTT.LastWill.Topic   := 'devices/lab-1/status';
MQTT.LastWill.Message := 'offline';
MQTT.LastWill.QoS     := mtqsAtLeastOnce;
MQTT.LastWill.Retain  := True;

4 · MQTT over WebSocket / WebSocket-Secure

For browser-paired clients or networks that block port 1883/8883, MQTT runs natively over WebSocket. Use the standard WebSocket subprotocol mqtt.

Transport.Host    := 'broker.hivemq.com';
Transport.Port    := 8884;
Transport.TLS     := True;
Transport.URL     := '/mqtt';
Transport.Subprotocol := 'mqtt';

Sources used to build this document

Every claim in this document maps back to a primary source. Use the links below to drill into the official references, the bundled help and the demo project that the code samples were reduced from.