TsgcWSPClient_MQTT

The MQTT component provides a lightweight, fully-featured MQTT client implementation with support for versions 3.1.1 and 5.0. The component supports plaintext and secure connections over both standard TCP and WebSockets.

Connection to a MQTT server is simple, you need to drop this component in the form and select a TsgcWebSocketClient Component using Client Property. Set host and port in TsgcWebSocketClient and set Active := True to connect.

MQTT v5.0 is not backward compatible (like v3.1.1). Obviously too many new things are introduced so existing implementations have to be revisited.

According to the specification, MQTT v5.0 adds a significant number of new features to MQTT while keeping much of the core in place.

The Clean Session flag functionality is divided into 2 properties to allow for finer control over session state data: the CleanStart parameter and the new SessionExpInterval.
Server disconnect: Allow DISCONNECT to be sent by the Server to indicate the reason the connection is closed.
All response packets (CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT) now contain a reason code and reason string describing why operations succeeded or failed.
Enhanced authentication: Provide a mechanism to enable challenge/response style authentication including mutual authentication. This allows SASL style authentication to be used if supported by both Client and Server, and includes the ability for a Client to re-authenticate within a connection.
The Request / Response pattern is formalized by the addition of the ResponseTopic.
Shared Subscriptions: Add shared subscription support allowing for load balanced consumers of a subscription.
Topic Aliases can be sent by both client and server to refer to topic filters by shorter numerical identifiers in order to save bandwidth.
Servers can communicate what features it supports in ConnectionProperties.
Server reference: Allow the Server to specify an alternate Server to use on CONNACK or DISCONNECT. This can be used as a redirect or to do provisioning.
More: message expiration, Receive Maximums and Maximum Packet Sizes, and a Will Delay interval are all supported.

Methods

Connect: this method is called automatically after a successful WebSocket connection.

Ping: Sends a ping to the server, usually to keep the connection alive. If you enable HeartBeat property, ping will be sent automatically by a defined interval.

Subscribe: subscribe client to a custom channel. If the client is subscribed, OnMQTTSubscribe event will be fired.

SubscribeProperties: (New in MQTT 5.0)

SubscriptionIdentifier: MQTT 5 allows clients to specify a numeric subscription identifier which will be returned with messages delivered for that subscription. To verify that a server supports subscription identifiers, check the "SubscriptionIdentifiersAvailable"
UserProperties: This property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them.

Example:


oProperties := TsgcWSMQTTSubscribe_Properties.Create;
Try
  oProperties.SubscriptionIdentifier := 16385;
  MQTT.Subscribe('myChannel', mtqsAtMostOnce, oProperties);
Finally
  FreeAndNil(oProperties);
End;

Unsubscribe: unsubscribe client to a custom channel. If the client is unsubscribed, OnMQTTUnsubscribe event will be fired.

UnsubscribeProperties: (New in MQTT 5.0)

UserProperties: This property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them.

Example:


oProperties := TsgcWSMQTTUnsubscribe_Properties.Create;
Try
  oProperties.UserProperties.Add('Temp=21');
  oProperties.UserProperties.Add('Humidity=55');
  MQTT.UnSubscribe('myChannel', mtqsAtMostOnce, oProperties);
Finally
  FreeAndNil(oProperties);
End;

Publish: sends a message to all subscribed clients. There are the following parameters:

Topic: is the channel where the message will be published.

Text: is the text of the message.

QoS: is the Quality Of Service of published message. There are 3 possibilities:

mtqsAtMostOnce: (by default) the message is delivered according to the best efforts of the underlying TCP/IP network. A response is not expected and no retry semantics are defined in the protocol. The message arrives at the server either once or not at all.

mtqsAtLeastOnce: the receipt of a message by the server is acknowledged by an ACKNOWLEDGMENT message. If there is an identified failure of either the communications link or the sending device or the acknowledgement message is not received after a specified period of time, the sender resends the message. The message arrives at the server at least once. A message with QoS level 1 has an ID param in the message.

mtqsExactlyOnce: where message are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied. If there is an identified failure of either the communications link or the sending device, or the acknowledgement message is not received after a specified period of time, the sender resends the message.

Retain: if True, Server MUST store the Application Message and its QoS, so that it can be delivered to future subscribers whose subscriptions match its topic name. By default is False.

PublishProperties: (New in MQTT 5.0)

PayloadFormat: select payload format from: mqpfUnspecified (which is equivalent to not sending a Payload Format Indicator) or mqpfUTF8 (Message s UTF-8 Encoded Character Data).
MessageExpiryInterval: Length of time after which the server must stop delivery of the publish message to a subscriber if not yet processed.
TopicAlias: is an integer value that is used to identify the Topic instead of using the Topic Name. This reduces the size of the PUBLISH packet, and is useful when the Topic Names are long and the same Topic Names are used repetitively within a Network Connection.
ResponseTopic: is used as the Topic Name for a response message.
CorrelationData: The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received.
UserProperties: This property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them.
SubscriptionIdentifier: A numeric subscription identifier included in SUBSCRIBE packet which will be returned with messages delivered for that subscription.
ContentType: String describing content of message to be sent to all subscribers receiving the message.

PublishAndWait: is the same method than Publish, but in this case, if QoS is [mtqsAtLeastOnce, mtqsExactlyOnce] waits till server processes the message, this way, if you get a positive result, means that message has been received by server. There is a timeout of 10 seconds by default, if after the timeout there is no response from server, the response will be false.

Disconnect: disconnects from MQTT server.

ReasonCode: code identifies reason why disconnects.(New in MQTT 5.0)

DisconnectProperties (New in MQTT 5.0)

SessionExpiryInterval: Session Expiry Interval in seconds.
ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.
ServerReference: can be used by the Client to identify another Server to use.

Auth: is sent from Client to Server or Server to Client as part of an extended authentication exchange, such as challenge / response authentication. (New in MQTT 5.0)

ReAuthenticate: if True Initiate a re-authentication, otherwise continue the authentication with another step.

AuthProperties

AuthenticationMethod: contains the name of the authentication method.
AuthenticationData: contains authentication data.
ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.

Events

OnMQTTBeforeConnect: this event is triggered before a new connection is established. There are 2 parameters:

CleanSession: if True (by default), the server must discard any previous session and start a new session. If false, the server must resume communication.

ClientIdentifier: every new connection needs a client identifier, this is set automatically by component, but can be modified if needed.

OnMQTTConnect: this event is triggered when the client is connected to MQTT server. There are 2 parameters:

Session:

If client sends a connection with CleanSession = True, then Server Must respond with Session = False.
If client sends a connection with CleanSession = False:

If the Server has stored Session state, Session = True.
If the Server does not have stored Session state, Session = False

ReasonCode: returns code with the result of connection.(New in MQTT 5.0)

ReasonName: text description of ReturnCode.(New in MQTT 5.0)

ConnectProperties: (New in MQTT 5.0)

SessionExpiryInterval: Session Expiry Interval in seconds.
ReceiveMaximum: number of QoS 1 and QoS 2 publish messages, the server will process concurrently for the client.
MaximumQoS: maximum accepted QoS of PUBLISH messages to be received by the server.
RetainAvailable: indicates whether the client may send PUBLISH packets with Retain set to True.
MaximumPacketSize: maximum packet size in bytes the server is willing to accept.
AssignedClientIdentifier: the Client Identifier which was assigned by the Server when client didn't send any.
TopicAliasMaximum: indicates the hishest value that the server will accept as a Topic Alias sent by the client.
ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.
WildcardSubscriptionAvailable: indicates whether the server supports wildcard subscriptions.
SubscriptionIdentifiersAvailable: indicates whether the server supports subscription identifiers.
SharedSubscriptionAvailable: indicates whether the server supports shared subscriptions.
ResponseInformation: used as the basis for creating a Response Topic.
ServerReference: can be used by the Client to identify another Server to use.
AuthenticationMethod: identifier of the Authentication Method.
AuthenticationData: string containing authentication data.

OnQTTDisconnect: this event is triggered when the client is disconnected from MQTT server. Parameters:

ReasonCode: returns code with the result of connection.(New in MQTT 5.0)

ReasonName: text description of ReturnCode.(New in MQTT 5.0)

DisconnectProperties: (New in MQTT 5.0)

SessionExpiryInterval: Session Expiry Interval in seconds.
ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.
ServerReference: can be used by the Client to identify another Server to use.

OnMQTTPing: this event is triggered when the client receives an acknowledgment from a ping previously sent.

OnMQTTPubAck: this event is triggered when receives the response to a Publish Packet with QoS level 1. There is one parameter:

PacketIdentifier: is packet identifier sent initially.

ReasonCode: returns code with the result of connection.(New in MQTT 5.0)

ReasonName: text description of ReturnCode.(New in MQTT 5.0)

PubAckProperties: (New in MQTT 5.0)

ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.

OnMQTTPubComp: this event is triggered when receives the response to a PubRel Packet. It is the fourth and final packet of the QoS 2 protocol exchange. There are the following parameters:

PacketIdentifier: is packet identifier sent initially.

ReasonCode: returns code with the result of connection.(New in MQTT 5.0)

ReasonName: text description of ReturnCode.(New in MQTT 5.0)

PubCompProperties: (New in MQTT 5.0)

ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.

OnMQTTPublish: this event is triggered when the client receives a message from the server. There are 2 parameters:

Topic: is the topic name of the published message.

Text: is the text of the published message.

PublishProperties: (New in MQTT 5.0)

PayloadFormat: select payload format from: mqpfUnspecified (which is equivalent to not sending a Payload Format Indicator) or mqpfUTF8 (Message s UTF-8 Encoded Character Data).
MessageExpiryInterval: Length of time after which the server must stop delivery of the publish message to a subscriber if not yet processed.
TopicAlias: is an integer value that is used to identify the Topic instead of using the Topic Name. This reduces the size of the PUBLISH packet, and is useful when the Topic Names are long and the same Topic Names are used repetitively within a Network Connection.
ResponseTopic: is used as the Topic Name for a response message.
CorrelationData: The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received.
UserProperties: This property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them.
SubscriptionIdentifier: A numeric subscription identifier included in SUBSCRIBE packet which will be returned with messages delivered for that subscription.
ContentType: String describing content of message to be sent to all subscribers receiving the message.

OnMQTTPubRec: this event is triggered when receives the response to a Publish Packet with QoS 2. It is the second packet of the QoS 2 protocol exchange. There are the following parameters:

PacketIdentifier: is packet identifier sent initially.

ReasonCode: returns code with the result of connection.(New in MQTT 5.0)

ReasonName: text description of ReturnCode.(New in MQTT 5.0)

PubRecProperties: (New in MQTT 5.0)

ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.

OnMQTTSubscribe: this event is triggered as a response to subscribe method. There are the following parameters:

PacketIdentifier: is packet identifier sent initially.

Codes: codes with the result of a subscription.

SubscribeProperties: (New in MQTT 5.0)

ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client about subscription.

OnMQTTUnSubscribe: this event is triggered as a response to subscribe method. There are the following parameters:

PacketIdentifier: is packet identifier sent initially.

Codes: codes with the result of a subscription.

UnsubscribeProperties: (New in MQTT 5.0)

UserProperties: provide additional information to the Client about subscription.

OnMQTTAuth: this event is triggered as a response to Äuth method. There is one parameter: (New in MQTT 5.0)

ReasonCode: returns code with the result of connection.

ReasonName: text description of ReturnCode.

AuthProperties:

AuthenticationMethod: contains the name of the authentication method used for extended authentication.
AuthenticationData: data associated to authentication.
ReasonString: represents the reason associated with this response. This Reason String is a human readable string designed for diagnostic.
UserProperties: provide additional information to the Client including diagnostic information.

Enhanced Authentication (New in MQTT 5.0)

To begin an enhanced authentication, the Client includes an Authentication Method in the ConnectProperties. This specifies the authentication method to use. If the Server does not support the Authentication Method supplied by the Client, it may send a Reason Code "Bad authentication method" or Not Authorized.

Example:

Client to Server: CONNECT Authentication Method="SCRAM-SHA-1" Authentication Data=client-first-data
Server to Client: AUTH ReasonCode="Continue authentication" Authentication Method="SCRAM-SHA-1" Authentication Data=server-first-data
Client to Server AUTH ReasonCode="Continue authentication" Authentication Method="SCRAM-SHA-1" Authentication Data=client-final-data
Server to Client CONNACK ReasonCode=0 Authentication Method="SCRAM-SHA-1" Authentication Data=server-final-data

Properties

MQTTVersion: select which MQTT version (3.1.1 or 5.0) will use to connect to server.

Authentication: disabled by default, if True a UserName and Password are sent to the server to try user authentication.

HeartBeat: enabled by default, if True, send a ping every X seconds (set by Interval property) to keep alive connection. You can set a Timeout too, so if after X seconds, the client doesn't receive a response to a ping, the connection will be closed automatically.

LastWillTestament: if there is a disconnection and is enabled, a message is sent to all connected clients to inform that connection has been closed.

Enabled: enable if you want activate last will testament.
Text: is the message that the server will publish in the event of an ungraceful disconnection.
Topic: is the topic that the server will publish the message to in the event of an ungraceful disconnection. Is mandatory if LastWillTestament is enabled.
Retain: enable if server must retain message after publish it.
WillProperties: (New in MQTT 5.0)
- WillDelayInterval: The Server delays publishing the Client’s Will Message until the Will Delay Interval has passed or the Session ends, whichever happens first.
- PayloadFormat: select payload format from: mqpfUnspecified (which is equivalent to not sending a Payload Format Indicator) or mqpfUTF8 (Message s UTF-8 Encoded Character Data).
- MessageExpiryInterval: Length of time after which the server must stop delivery of the will message to a subscriber if not yet processed.
- ContentType: string describing content of will message.
- ResponseTopic: Used as a topic name for a response message.
- CorrelationData: binary string used by client to identify which request the response message is for when received.
- UserProperties: can be used to send will related properties from the Client to the Server. The meaning of these properties is not defined by MQTT specification.

ConnectProperties: (New in MQTT 5.0) are connection properties sent with packet connect.

Enabled: if True, connect properties will be sent to server.
SessionExpiryInterval: if value is zero, session will end when network connection is closed.
ReceiveMaximum: the Client uses this value to limit the number of QoS 1 and QoS 2 publications that it is willing to process concurrently.
MaximumPacketSize: the Client uses the Maximum Packet Size to inform the Server that it will not process packets exceeding this limit.
TopicAliasMaximum: the Client uses this value to limit the number of Topic Aliases that it is willing to hold on this Connection.
RequestResponseInformation: the Client uses this value to request the Server to return Response Information in the CONNACK. If False indicates that the Server MUST NOT return Response Information, If True the Server MAY return Response Information in the CONNACK packet.
RequestProblemInformation: the Client uses this value to indicate whether the Reason String or User Properties are sent in the case of failures. If the value of Request Problem Information is False, the Server MAY return a Reason String or User Properties on a CONNACK or DISCONNECT packet but MUST NOT send a Reason String or User Properties on any packet other than PUBLISH, CONNACK, or DISCONNECT.
UserProperties: can be used to send connection related properties from the Client to the Server. The meaning of these properties is not defined by MQTT specification.
AuthenticationMethod: contains the name of the authentication method used for extended authentication.