Version 0.5.3
A basic MQTT client written in Free Pascal/Lazarus that can publish messages to a broker while being subscribed to one or more topics with the same broker. It uses the Eclipse mosquitto library to communicate with the MQTT broker. lazmqttc can be seen as the Eclipse utility mosquitto_rr with a graphical interface and some additional capabilities.
The screen capture shows the message sent to the public test.moquitto.org broker and it's reply. In this example, the client is subscribed to the same topic used to send the message, which in many cases would not be done.
- 1. Requirements
- 2. Compiling
- 3. Testing
- 4. Installation
- 5. Program Options
- 6. Option Overrides at Runtime
- 7. Broker Definitions
- 8. Log
- 9. National Language Support
- 10. Improvements and Development
- 11. Acknowledgment
- 12. Licence
Two Free Pascal units are required
mosquitto.pas- conversion of the Cmosquitto.hheader to Pascal, provides the same API as the C versionmqttclass.pas- Object Pascal wrapper class to ease the integration of libmosquitto into Object Oriented
These files, found in the mosquitto-p directory, are copied from the GitHub repository with the same name by Károly Balogh (chainq).
In addition the Eclipse mosquitto library must be installed on the system.
The libmosquito library is needed. In Debian systems this means installing two packages:
libmosquitto1libmosquitto-dev
The first, libmosquitto1 will probably already be installed if the mosquitto-clients package is available on the system. In Debian-based systems these packages can be installed with a package manager such as Synaptic or from the command line.
$ sudo apt install libmosquitto1 libmosquitto-dev
There is no requirement to install the mosquitto MQTT broker.
-
Get the latest binary package from Eclipse mosquitto Download. Version 2.0.10 is available as of May 5, 2021. Chose the appropriate 64-bit installer (
mosquitto-2.0.10-install-windows-x64.exe) or 32-bit installer (mosquitto-2.0.10-install-windows-x32.exe). -
Click on the downloaded application to install the package. It is not necessary to install it as a service if an MQTT broker is not needed.
- The 64-bit package was installed in
C:\Program Files\mosquitto\.- The 32-bit package will probably go into
C:\Program Files (x86)\mosquitto\.
- Test the
mosquitto_subandmosquitto_pubutilities from the command line using the host name or IP address of a reachable MQTT broker instead of <mqtt_broker>.
C:\Users\michel>"c:\Program Files\mosquitto\mosquitto_sub" -h <mqtt_broker> -t "#"
- Copy the mosquitto libraries
C:\Program Files\mosquitto\mosquitto.dll C:\Program Files\mosquitto\mosquitto_dynamic_security.dll C:\Program Files\mosquitto\libcrypto-1_1-x64.dll C:\Program Files\mosquitto\libssl-1_1-x64.dll C:\Program Files\mosquitto\mosquittopp.dll
to the same folder containing the compiledlazmqttc.exeexecutable. Depending on use, they may not all be necessary, but the first two are needed without doubt.
It is left as an exercise for knowledgable Windows users to find a more elegant way of ensuring that the DLLs are found.
Ultimately, if a mosquitto MQTT broker is to be run on the system, it may make more sense to simply copy lazmqttc.exe into the mosquitto directory alongside the mosquitto_rr.exe, mosquitto_pub.exe and mosquitto_sub.exe utilities it emulates.
Warning: The application seems to freeze when connecting to the localhost if it is not running an MQTT broker.
[MQTT] [mqttClient] INFO Connecting to [localhost:1884] - SSL:False
[MQTT] [mqttClient] INFO Broker disconnected: Connection lost
[MQTT] [mqttClient] INFO Next reconnection attempt in 60 seconds.
[MQTT] [mqttClient] INFO Reconnecting to [localhost:1884] - SSL:False
The first log entry will be shown right away, but it will take a minute or so before the following two entries are shown and the application responds normally. This behaviour was not observed in Linux and it may not be present if an MQTT broker is running on the local machine.
The repository is self-contained (except for the mosquitto library of course), so creating this tool should be straightforward. Clone the repository, start the Lazarus IDE, load the project, and compile.
The project uses a custom component, a "virtual grid" to display subscribed topics. This component is so specialized that there is no point in adding it to the IDE component palette. Instead the component is created at runtime in the FormCreate methods of the main and broker edit forms. Consequently, the component is not visible in the form designer.
When compiling a final version, it would be advisable to heed the following advice.
-
Modify the default password encryption key 'DEFAULT_KEY' in the 'units/pwd.pas' file. That way it will not be easy for any one of the vast number of users of this application to read a broker definition file and obtain the MQTT broker password. See 5.1. Security Warning for more details.
-
Add an application icon. Select
Load IconinProject / Project Optionsin the Lazarus IDE. Thelazmqttc.pngimage theimagesdirectory can be used. The filelazmqtt.lzpis the LazPaint source for the image file. -
Compile the release version. Select the
Releasebuild mode inProject / Project Options / Compiler Optionsin the Lazarus IDE. This will reduce the size of the executable by an order of magnitude.
The project was built with Lazarus 2.2.0RC2 (Free Pascal 3.2.3) on a Mint 20.1 system with version 1.6.9-1 of the mosquitto libraries.
A cursory test was done with Lazarus 2.0.12 (Free Pascal 3.2.0) in Windows 10.
There are unit tests of the TBroker class, but they may be out of date.
Warning: No testing of SSL encryption has been performed.
The installation directory contains a lazmqttc.desktop file along with rudimentary instructions on how to install the utility in a Mint 20.1 Mate system. Presumably, installation in other Linux distributions would be more or less the same.
Details about installation of an application in Windows 10 are unfortunately not provided.
Starting with version 0.4.0, program options can be changed at runtime. Click on the Options button at the bottom right of the application window to enter the options editor.
Modifying options (described next) has no immediate effect until the Accept button is pressed. In that case, the options editor will be immediately closed. The Cancel button will close the options editor with a prior verification that any modification will be lost. The Reset button will restore all options to their default values as defined in the options.inc file.
If automatic connection is enabled, then an attempt will be made to open a connection to the MQTT broker if one is not already established when a message is published. When such an attempt is made, the program will wait for the specified number of seconds and then publish the message if the connection has been established. Even if the program reports that it was unable to establish a connection, it is still possible that the broker will respond later.
The public MQTT server at mosquitto.org may very well take more than the default 5 seconds to respond to an initial connection request. It was necessary to press the Publish button again once the connection was made to get the response shown in the screenshot at the top of this page.
If Auto clear previous messages on publishing a message is checked then the Messages control is cleared of old messages when a new message is published to the broker.
It is possible to define the maximum number of messages that can be shown in the Messages control. Older messages are removed as new messages come in if necessary.
If Show published messages is checked then published messages are added in the control no matter if the client is subscribed to these messages or not. In the screenshot the
If Show message topics is not checked then only message payloads are shown in the Messages control. When shown, topics are enclosed in square brackets [<topic>].
The Received message header and Published message header are used to define prefixes that identify which messages are sent and which are received.
The Default broker field can be entered to set a broker definition file that will be loaded when the program starts.
It is possible to override each of three messages options when the program is running.
| Option override checkbox | Messages option |
|---|---|
Auto clear |
Auto clear previous messages on publishing a message |
Show |
Show published messages |
Show topics |
Show message topics |
A change in a runtime override does not affect the corresponding messages option, it only modifies the manner in which messages received from then on will be displayed. Messages options are default values for the option overrides loaded when the program starts. These default can only be changed in the Options window.
MQTT broker definitions can be retrieved, saved, edited or created by clicking on the Edit button at the top of the main program window. Editing the current MQTT definition is the only way to add, remove or change the list of subscribed topics.
MQTT broker definitions are JSON formatted text files. The res directory contains examples of broker definition files.
Prior to version 3.3, the MQTT broker passwords were stored in plain text in the broker definitions file. Do not save MQTT broker passwords in the broker definition screen in these older versions.
A quick fix was added in version 3.3 so that an encrypted password will be saved in the broker definition file. A default encryption key is defined which should be changed if compiling the program (see 2. Compiling for details). However those using binary releases can override the default key by storing a different key in a file named key.txt in the directory that contains the broker definition files. The file should contain the key on one line and nothing else. Since this is a plain text file, this is not to be considered secured at all.
Note that the MQTT user and password are transmitted in plain text over an HTTP connection, so truly secure handling of the MQTT password will have to wait until communication with the broker using the HTTPS protocol is implemented.
Starting with version 0.5.0, the application log messages can be viewed. These are the messages produced by the TMQTTConnection object (defined in mqttclass.pas and the underlying Mosquitto library. The log level is set in the Log window context menu obtained with a right mouse button click.
Unlike the usual implementation, in Linux at least, setting a log level does not set all levels with higher priority. In other words, each level can be set or reset independently. It seems that some levels are not implemented. For example, no messages are generated when topics are changed when the subscribe and unsubscribe log levels are set.
The languages directory contains national language translations of the literal strings found in the program. This directory should be copied alongside the executable file.
Only a single translation into French is provided: lazmqttc.fr.po. However there is a template file, lazmqttc.po, that can be used to create a translation into other languages.
The choice of language is done automatically based on the system locale when the program starts up. There is no provision for choosing the language at run-time. Those that prefer to use the English language version even if a translation into the national language exists can achieve their goal by renaming or erasing the languages directory.
Initially this utility was quickly cobbled to fulfill an immediate need: wrangling a number of IoT devices running Tasmota firmware mostly to get their IP address. Since then, an attempt has been made to combine the important features of the mosquitto "pub and sub clients" into a single application. At the same time, some attention has been given to cleaning up the code, but improvements are certainly possible. All suggestions welcome.
There are aspects of the MQTT protocol that are not implemented including the Last Will and Testament feature and clean sessions.
Obviously, this utility would not have been possible without
- the Free Pascal and the Lazarus Ide projects
- the Eclipse Mosquitto project and
- the mosquitto-p project by Károly Balogh (chainq).
Not quite as obvious, the JSON data viewer by Michael Van Canneyt (named jsonviewer) provided the code for saving and loading the JSON broker definition and the JSON program option files. The utility can be found in the tools directory in the Lazarus source. The full path is /usr/share/lazarus/2.0.12/tools/jsonviewer in a default installation of Lazarus in Mint 20.1.
The broker password encryption using the Free Pascal Blowfish unit is based on a blog post by leledumbo Blowfish, the cryptography unit by leledumbo (June 24, 2012).
The Eclipse Mosquitto project is dual-licensed under the Eclipse Public License 2.0 and the Eclipse Distribution License 1.0.
The content of the mosquito-p repository is covered by the ISC License (SPDX: ISC).
Except for eye.png and no_eye.png, the icons used in the broker editor form were copied from the Lazarus distribution which is provided under a modified LGPL licence (see COPYING.modifiedLGPL.txt in the Lazarus source tree. The source of the check list box editor (also covered by the modified LGPL licence) in the Lazarus IDE was the initial inspiration for the subscribed topics editor.
The BSD Zero Clause (SPDX: 0BSD) licence applies to the original code in this repository.