======MQTT======

MQTT is a standard messaging protocol mainly used for Internet of Things devices (IoT). It is designed as a lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with minimal network bandwidth requirements. 

:!: Support for MQTT was added in Blocks version 6.1. Thus, you need that version or later to follow this guide.
=====Principle of MQTT Messaging=====


====MQTT Broker====

The broker acts as an intermediary, providing an MQTT "bus" through which other devices and programs can connect. It's responsible for receiving all MQTT messages and passing them on to subscribers. From the broker's perspective, Blocks is just another MQTT client. The common //Mosquitto// MQTT broker comes pre-installed on our Linux server image. 

====MQTT Clients====
An MQTT client is basically any device or program that interacts with the broker to send or receive messages. Examples of MQTT devices include sensor delivering data at constant intervals.
A client can subscribe to a given //topic//, provided through the broker, to then receive messages sent on that topic. Similarly, a client can publish messages under a topic, to be forwarded by the broker to subscribers of that topic. 
====Topic====
Topics are used to register interest in a specific incoming message type and, conversely, to specify where to publish outbound messages. Topics are often arranged hierarchically, using several levels separated by a forward slash. Here are some examples:

<code>
myvenue/meetingrooms/heaven/temperature
myvenue/meetingrooms/sea/temperature
myvenue/meetingrooms/sea/ambience
</code>

You can think of a topic as a //named channel// through which messages can be passed.

====MQTT Message====
Blocks supports text messages only (UTF-8 encoded), which is what's used by the vast majority of MQTT devices. Text data can be structured in many ways, such as JSON, XML or plain text. A //device driver// is used in Blocks to encode/decode the MQTT messages to/from the device, presenting the result as standard Blocks properties and task-accessible functions.

=====MQTT in Blocks=====
MQTT in itself is just the message transport mechanism. The data carried in these messages varies widely depending on the brand or device. Blocks uses device drivers to create and interpret MQTT message, just as it does for other transports such as TCP or UDP.

{{:blocks:server:advanced_server_configuration:mqtt:mqtt-illustration-black.png?400|}}

====Enabling the Broker==== 
While any broker can be used, the [[https://mosquitto.org/|Mosquitto message broker]] comes pre-installed on our [[blocks:linux|Linux server image]] beginning with version 221214.  
To enable the broker, follow these steps.

===Installing the Broker===
This step only applies if you have an existing Linux Blocks server prior to version 221214, where the broker is not yet available. Open a terminal window and perform the following commands

<code>
su pixi-admin
sudo apt update
sudo apt -y install mosquitto
</code>

Enter the password of the pixi-admin user when required. Default password here is //pixi// in case you haven't changed it (shame on you!).

===Firewall Considerations===
The firewall is disabled by default in the Blocks server. 
To check if the firewall has been enabled, run the following commands under the pixi-admin user (switch to this user using the //su pixi-admin// command as shown above, if required).

<code>
sudo ufw status
</code>

If response is: 
<code>
Status: inactive
</code>
then the firewall is turned off and no further actions is required.

If the response indicates that the firewall is active, you must allow the MQTT port to be used.

<code>
sudo ufw allow 1883
</code>

===Running the Broker===
This command will enable and start //mosquitto// as a system service. Once it is enabled, it will be started automatically if you restart your server.

<code>sudo systemctl enable --now mosquitto</code>

===Configuring the Broker===

The following commands assume you're logged into the terminal as the pixi-admin user. If not use the //su pixi-admin// command to switch to that user, as described above.

The Mosquitto broker's configuration is stored under// /etc/mosquitto/conf.d/ //

List that directory to see if there's already a configuration file:

<code>
ls /etc/mosquitto/conf.d/
</code>

If the directory is empty, add the configuration file like this:
<code>
sudo nano /etc/mosquitto/conf.d/pixi.conf
</code>

Then paste in the following configuration into the empty editor window:

<code>
listener 1883
# Enable either one of the following depending on whether you want
# password authentication or not
# password_file /etc/mosquitto/conf.d/pixi-pwd
allow_anonymous true
</code>

The first line makes the broker listen to requests on port 1883, which is the standard MQTT TCP port.
The //allow_anonymous true// setting makes the broker accept anonymous clients (i.e., clients do not have to specify username and password).

To make the nano editor save the text, press ctrl+o followed by the Enter key. To close the editor, press ctrl+x on the keyboard. 

Restart mosquitto to apply the new configuration.

<code>
sudo systemctl restart mosquitto.service
</code>

====Security====
The broker can be configured to require client authentication using a username and password before a connection is permitted. 

:!: **NOTE**: The username and password combination is transmitted in clear text, and is not secure without some form of transport encryption involving certificates manually distributed to and configured on all clients. 

===Adding a Password File===

The following commands assume you're logged into the terminal as the pixi-admin user. If not use the //su pixi-admin// command to switch to that user, as described above.

<code>
sudo mosquitto_passwd -c pixi-pwd blocks
</code>

Change the broker configuration and add the line that specifies a password file and turn off the option to use the broker as anonymous user.
<code>
listener 1883
# Enable either one of the following depending on whether you want
# password authentication or not
password_file /etc/mosquitto/conf.d/pixi-pwd
allow_anonymous false
</code>

===Secure connection (TLS)===

Any MQTT application that is running over the internet or Local Area Network accessible by general public should use secure connections and password authentication. To enable TLS with a self signed certificate on the mosquitto broker please follow this article.  

[[blocks:server:advanced_server_configuration:mqtt:mosquitto_tls|Add certificates for Mosquitto MQTT broker secure connections]]

==== Blocks Server Configuration File ====

If you do not know about the server configuration file, [[blocks:server_configuration_file|catch up here.]]

:!: **NOTE**: This feature was added in Blocks 6.1. If you're using an older version, this section does not apply to you.

If this section is missing in the config file, default settings is assumed for the broker. 
<code>
mqtt:
  defaultBroker:
    address: localhost  # Default is localhost
    username: pixi   # Default is no username and password
    password: pixi
    encryption: false  # Set to true if secure connection (tls) is available.
    port: 1883 # Default is 1883 if non-encypted and 8883 if encrypted
</code>


In the standard case, no explicit MQTT configuration is required, in which case a default broker connection to //localhost// with no username or password will be attempted. This is appropriate when using the MQTT broker included with our [[blocks:server:advanced_server_configuration:mqtt|Linux server image]] version 221214 and later.

:!: **NOTE**: In addition to an MQTT broker, a suitable device driver is required for the device you want to control (here's an [[https://github.com/pixilab/blocks-script/blob/6.1/driver-archive/ShellySwitchGen1.ts|example MQTT driver]]).


If you want to use a broker running on another computer, specify its IP address or name using the //address// setting as shown above. If your broker [[blocks:server:advanced_server_configuration:mqtt#security|requires authorization]] in order to connect, you must also specify the //username// and //password// options as expected by your broker's configuration.

:!: **NOTE**: These are the credentials of your MQTT broker – not your Blocks server.


====Add a MQTT Device in Blocks====

Follow the MQTT section in the [[https://pixilab.se/outgoing/blocks/PIXILAB-Blocks.pdf|The Blocks Manual]] for details how to add and configure MQTT devices in Blocks editor once the server has been prepared for MQTT. 
====MQTT Explorer (3rd party tool)====

We have successfully used this tool to explore and get a visual view over the current broker topics. The tools is also perfect to test mqtt devices functionality outside Blocks. 
[[https://mqtt-explorer.com/|MQTT Explorer]]

The two following screenshots show connection examples.


Without TLS encryption:

{{:blocks:server:advanced_server_configuration:mqtt:skaermbild_2023-05-16_133427.png|}}

Without TLS encryption:

{{:blocks:server:advanced_server_configuration:mqtt:skaermbild_2023-05-16_133403.png|}}

After successful connection the  $SYS/broker topic should appear. This is some statistics published by the broker itself.
 
{{:blocks:server:advanced_server_configuration:mqtt:skaermbild_2023-05-16_133551.png|}}


Credits to Thomas Nordquist for the great work.