ClientConnection Quick Start

Adding MQTTLib module to your project

• Download and open the latest MQTTLib-demo project available in the GitHub repository here.
• Drag & drop (or copy & paste) both MQTTLib and zd modules into your project.

You're all set.

Setup and connect the ClientConnection as a window control

In a window, drag & drop a ClientConnection form the MQTTLib module and name it MQTTClient. Use the following code in a method to connect to the server.

// Create and setup the socket
Dim theSocket As New TCPSocket

theSocket.Address = "test.mosquitto.org" // Change for your server address
theSocket.Port = MQTTLib.kDefaultPort

// Create and setup the connection options
Dim theConnectOptions As New MQTTLib.OptionsCONNECT

theConnectOptions.KeepAlive = 30
theConnectOptions.ClientID = "Client12345678" // Use your own client id
theConnectOptions.CleanSessionFlag = True

Me.MQTTClient.Setup New MQTTLib.TCPSocketAdapter( theSocket ), theConnectOptions
Me.MQTTClient.Connect

For simple setup like unsecure TCP with no last will and no credentials you can use the EasyTCPConnection() method:

Me.MQTTClient.EasyTCPConnect( "test.mosquitto.org", MQTTLib.kDefaultPort "Client12345678", True, 30 )

The values used may change depending on your setup.

If the connection is successful, the BrokerConnected(inSessionPresentFlag As Boolean) event is triggered. In case of error the BrokerConnectionRejected(inErrorCode As Integer) is triggered and the inErrorCode parameter will explain why.

Publishing

You can use the OptionsPUBLISH class to setup the message you want to publish.

Dim theMessage As New MQTTLib.OptionsPUBLISH
 		  
theMessage.Message = "Hello World"
theMessage.TopicName = "Test/World"
theMessage.QoSLevel = MQTTLib.QoS.AtLeastOnceDelivery

// Set the packet ID. You may need to store the value for further use.
Dim thePacketID As UInt16 = Self.MQTTClient.NewPacketID
theMessage.PacketID = thePacketID

// Publish the message
Self.MQTTClient.Publish theMessage

If you're not providing a packet id, one will automatically be assigned by the ClientConnection instance right before sending the control packet. If you need it after the sending, check __theMessage.PacketID__property. You can use your own packet id but it's entirely up to you to assign it and store it. Always calling ClientConnection.NewPacketID is strongly recommended to avoid any conflicts.

Depending on the QoS (Quality of Service) used, you may have to handle one or two of the following events:

1. At Most Once Delivery
   • There is no further process for this QoS.
2. At Least Once Delivery
   • ReceivedPUBACK(inPacketID As UInt16
3. Exactly Once Delivery
   • ReceivedPUBREC(inPacketID As UInt16) As Boolean
   • ReceivedPUBCOMP(inPacketID As UInt16) As Boolean

Subscribing

The OptionsSUBSCRIBE lets you subscribe to one or more topic with different QoS in a single message in a very simple way. OptionsSUBSCRIBE support the use of the topic level separator / ( U+002F), the multi-level wildcard # (U+0023), the single-level wildcard +(U+002B).

// Create and populate the options
Dim theOptions As New MQTTLib.OptionsSUBSCRIBE

// You can add multiple topics in a single SUBSCRIBE control packet
theOptions.AddTopic "Test/World", MQTTLib.QoS.ExactlyOnceDelivery

// Send the SUBSCRIBE options
Self.MQTTClient.Subscribe theOptions

After receiving the subscribing request, the server will answer with a single SUBACK control packet to confirm or deny the subscribtion for each topic. This will trigger the ReceivedSUBACK(inSUBACKData As MQTTLib.OptionsSUBACK) event and the inSUBACKData wil contains the server response.

⚠️ Topics name restrictions

• Publishing to topics with a leading $ character is not recommended
• Topic names are case sensitive
• A topic name can't be empty nor including a NULL character (U+0000).
• Topic names are UTF-8 encoded but their binary length is limited to 65535 bytes.

More informations about topic names and topic filters are available here in the section 4.7.

Receiving Messages

When the client receives a message, the ReceivedPUBLISH() As Boolean event is triggered. The inPublish parameter will hold the message, the topic, the QoS level and the PacketID.

Sub ReceivedPUBLISH(inPublish As MQTTLib.OptionsPUBLISH) Handles ReceivedPUBLISH

  MsgBox "PUBLISH received with packet id #" + Str( inPublish.PacketID ) _
     + EndOfLine + EndOfLine + "Topic: " + inPublish.TopicName + EndOfLine _
     + "Message: " + inPublish.Message

End Sub

The QoS used may require further control packet sending. If you return False, the client will handle the response itself. Otherwise (i.e. returning True) it will assume you handle the reply by yourself. This is also true for the ReceivedPUBREC() and ReceivedPUBREL() events.

Depending of the QoS events further steps will occur.

1. At Most Once Delivery
   • There is no further process.
2. At Least Once Delivery
   • The client must send a PUBACK control packet. No further sending is needed.
3. Exactly Once Delivery
   • The Client must send a PUBREC control packet.
   • The server will reply with a PUBREL control packet, trigerring the ReceivedPUBREL(inPacketID As UInt16) As Boolean event.
   • The client must send a PUBCOMP control packet. This will end the exchange.

Unsubscribing

Use the OptionsUNSUBSCRIBE class to unsubscribe from a single, or more, topic.

// Create and populate the options
Dim theOptions As New MQTTLib.OptionsUNSUBSCRIBE

// You can add several topic name in a single UNSUBSCRIBE control packet
theOptions.AddTopicName "Test/World"

// Set the packet ID. You may need to store the value for further use.
Dim thePacketID As UInt16 = Self.MQTTClient.NewPacketID
theOptions.PacketID = thePacketID

// Send the SUBSCRIBE options
Self.MQTTClient.Unsubscribe theOptions

The server will reply with a SUBACK control packet that has the same packet ID to confirm the unsubscription. This will trigger the ReceivedUNSUBACK(inPacketID As UInt16) event.

Disconnect

To cleanly close the connection from the server, simply call the MQTTClient.Disconnect() method.

A clean disconnection implies the following:

• The server will discard any Last Will message without publishing it.
• The network connection established by the SocketAdapter is closed.
• The triggerring of the Error(inMessage As String, inError As MQTTLib.Error) event with the inError parameter's value set to MQTTLib.Error.LostConnection.
• The ClientConnection.Connected will return False.