TclMQTTClient

function AddNewMQTTClient(AComponent: TCLComponent; xName: string): TCLMqttClient;

TCLMqttClient component is a lightweight MQTT client used to connect, publish, and subscribe to MQTT brokers. It supports common MQTT operations such as publishing messages, subscribing to topics, receiving messages, and handling connection events.

Information: What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol designed for low bandwidth, high latency, and simplicity. It is ideal for resource-constrained IoT devices.

Core Components and Operation

MQTT communication revolves around three main components: Broker, Publisher, and Subscriber.

Component	Description
Broker (Server)	The central server that manages and routes all messages. It is essential for clients to communicate.
Publisher (Client)	The client that sends messages to a specific Topic.
Subscriber (Client)	The client that subscribes to topic(s) of interest and receives messages.
Topic	Channels where messages are sent and subscribed to. They can be hierarchical (e.g., chat/general, sensors/temp).

• You must use a Broker to utilize the TCLMqttClient during development.
• Ports: Standard (Non-TLS): 1883, Secure (TLS/SSL): 8883.

Important Note: Security

If you are using a Broker accessible via the Internet, you must secure it with TLS/SSL and a Username/Password.

TCLMqttClient Properties, Methods, and Events

Feature	Use of	Definition
TCLMqttClient	clMqttClient : TCLMqttClient;	A variable belonging to the MQTT client object is created.
AddNewMqttClient	clMqttClient = MyForm.AddNewMQTTClient(MyForm,'clMqttClient');	A new MQTTClient is added to the form.
BrokerHost	clMqttClient.BrokerHost = '192.168.1.10';	Sets the MQTT broker host address (IP or domain).
Port	clMqttClient.Port = 1883;	Sets the MQTT broker port. Common ports: 1883 (non-TLS), 8883 (TLS/SSL).
Username	clMqttClient.Username = 'user';	Username for broker authentication (Optional).
Password	clMqttClient.Password = 'password';	Password for broker authentication (Optional).
Channel	clMqttClient.Channel = 'chat/general';	Default topic for publishing messages.
Connect	clMqttClient.Connect;	Initiates connection to the broker.
Disconnect	clMqttClient.Disconnect;	Disconnects from the broker.
Send	clMqttClient.Send('Hello', 1, False);	Publishes a message to the configured channel. Parameters: Payload, QoS, Retain.
Subscribe	clMqttClient.Subscribe('sensors/#', 1);	Subscribes to the specified Topic with the specified QoS.

Feature	Definition
tbeOnMQTTClientConnected	This is the trigger event used when the client successfully connects to the Broker.
tbeOnMQTTClientDisconnected	This is the trigger event used when the client disconnects from the Broker.
tbeOnMQTTClientMessage	This is the trigger event used when a message is received from a subscribed topic.

Tip: Understanding Topic Wildcards in Subscriptions

When subscribing, you can use two wildcards to listen to multiple related topics: # (Multi-level wildcard): Matches any number of topic levels at the end. Example: home/sensors/# subscribes to home/sensors/temp/attic, home/sensors/humidity, and all topics starting with home/sensors/. + (Single-level wildcard): Matches only one topic level. Example: chat/+/status subscribes to chat/user1/status and chat/user2/status, but NOT to chat/general/room/status.

Information: QoS Levels

QoS 0 (At Most Once): Message is sent at most once. Fastest, least reliable. QoS 1 (At Least Once): Message delivery is guaranteed at least once. Duplicate messages may occur. QoS 2 (Exactly Once): Message delivery is guaranteed exactly once. Slowest, most reliable.

Example: Basic MQTT Client

var
 MyForm:TCLForm;
 clMqttClient:TCLMqttClient;
 testEdit : TclEdit;
 testButton : TclButton;
 noteMemo : TclMemo;

void testButtonOnClick{
 if (testEdit.Text <> '')
  {
   clMqttClient.Send(testEdit.Text, 1, False); // QoS=1, retain=false
   testEdit.Text = '';
  }
 }

void MQTTClientOnConnected{
 noteMemo.Lines.Add('~Connected to Broker~');
 clMqttClient.Subscribe('chat/#', 1); // listen all starts with "chat/"
 }


void MQTTClientOnDisconnected{
 noteMemo.Lines.Add('~Connection lost from Broker~');
 }

void MQTTClientOnMessage{
 noteMemo.Lines.Add('~~~~~~~~~~~~~~'+#13#10+
 '[Topic]:['+MyForm.clTopic+']'+#13#10+
 '[Payload]:['+MyForm.clPayload+']'+#13#10+
 '~~~~~~~~~~~~~~~'
 );
}

void MQTTClientImplement{

 clMqttClient = MyForm.AddNewMQTTClient(MyForm,'clMqttClient');
 
 MyForm.AddNewEvent(clMqttClient,tbeOnMQTTClientConnected,'MQTTClientOnConnected');
 MyForm.AddNewEvent(clMqttClient,tbeOnMQTTClientDisconnected,'MQTTClientOnDisconnected');
 MyForm.AddNewEvent(clMqttClient,tbeOnMQTTClientMessage,'MQTTClientOnMessage');
 
 clMqttClient.BrokerHost = '192.168.5.30'; // Local Adress
 clMqttClient.Port = 1883; // Port
 clMqttClient.Username = 'testuser'; // Username
 clMqttClient.Password = '123321'; // Password
 clMqttClient.Channel = 'chat/testroom'; // Channel
 clMqttClient.Connect;
}

{
 MyForm = TCLForm.Create(Self);
 
 noteMemo = MyForm.AddNewMemo(MyForm,'noteMemo','');
 noteMemo.align = alClient;
 noteMemo.Margins.Bottom=10
 
 testEdit = MyForm.AddNewEdit(MyForm,'testEdit','');
 testEdit.Height = 50;
 testEdit.align = alBottom;
 testEdit.Margins.Bottom=10;
 
 testButton = MyForm.AddNewButton(MyForm,'testButton','Send Message');
 testButton.Margins.Bottom=20;
 testButton.align = alMostBottom;
 testButton.OnClick='testButtonOnClick'
 
 MQTTClientImplement;
 MyForm.Run;
}

See Also

• Components
• AddNewEvent
• TclMQTT