PIXILAB Wiki

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
blocks:server:advanced_server_configuration:mqtt [2023-05-16 11:43]
mattias [3rd party tools.] 		blocks:server:advanced_server_configuration:mqtt [2025-01-13 12:03] (current)
mattias [Blocks Server Configuration File]
Line 3: Line 3:
 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.  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===== =====Principle of MQTT Messaging=====
  
Line 14: Line 15:
 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.  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==== ====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 heriarchically, using several levels separated by a forward slash. Here are some examples:+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> <code>
Line 28: Line 29:
  
 =====MQTT in Blocks===== =====MQTT in Blocks=====
-MQTT in itself is just the message transport mechanism. The data carried in these mesages 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.+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|}} {{:blocks:server:advanced_server_configuration:mqtt:mqtt-illustration-black.png?400|}}
  
 ====Enabling the Broker====  ====Enabling the Broker==== 
-While any broker can be used, the [[https://mosquitto.org/|Mosquitto message broker]] comes pre-istalled on our [[blocks:linux|Linux server image]] beginning with version 221214.  +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. To enable the broker, follow these steps.
  
Line 74: Line 75:
 ===Configuring the Broker=== ===Configuring the Broker===
  
-The following commands assume you're logged into the terminal as the pixi-amdin user. If not use the //su pixi-admin// command to switch to that user, as described above.+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/ // The Mosquitto broker's configuration is stored under// /etc/mosquitto/conf.d/ //
Line 113: Line 114:
 The broker can be configured to require client authentication using a username and password before a connection is permitted.  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 manualy distributed to and configured on all clients. +:!: **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=== ===Adding a Password File===
  
-The following commands assume you're logged into the terminal as the pixi-amdin user. If not use the //su pixi-admin// command to switch to that user, as described above.+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.
  
 +Make sure we have a password file to store the users (this will not overwrite if the file already exist:
 <code> <code>
-sudo mosquitto_passwd -c pixi-pwd blocks+sudo touch  /etc/mosquitto/conf.d/pixi-pwd
 </code> </code>
  
-Change the broker configuration and add the line that specifies a password file and turn off the option to use a the broker as anonymous user.+Set file ownership and restrictive permissions for the password file: 
 +<code> 
 +sudo chmod 400 /etc/mosquitto/conf.d/pixi-pwd 
 +sudo chown mosquitto:mosquitto /etc/mosquitto/conf.d/pixi-pwd 
 +</code> 
 + 
 +Create a user in mosquitto, the example command adds a user named blocks to an existing password file, the dialog o will prompt for a password.  
 +<code> 
 +sudo mosquitto_passwd  /etc/mosquitto/conf.d/pixi-pwd blocks 
 +</code> 
 + 
 +Read the manual for mosquitto_password to find out other options such as delete a user etc. Note, if the -c option is being used the existing file is overwritten and the file permissions must reset as mosquitto runs with limited permissions for security reasons. 
 + 
 +mosquitto_password will throw a warning when adding user while the password file is owned by mosquitto, with this permissions and ownership only root and mosquitto can read the file and mosquitto cannot modify it. It is possible but currently not necessary to temporary change ownership back to root:root while adding new users to mosquitto. 
 + 
 +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> 
 +sudo nano /etc/mosquitto/conf.d/pixi.conf 
 +</code> 
 +The settings:
 <code> <code>
 listener 1883 listener 1883
Line 130: Line 152:
 password_file /etc/mosquitto/conf.d/pixi-pwd password_file /etc/mosquitto/conf.d/pixi-pwd
 allow_anonymous false allow_anonymous false
 +</code>
 +
 +Execute the change we must restart the service:
 +<code>
 +sudo systemctl restart mosquitto.service
 </code> </code>
  
 ===Secure connection (TLS)=== ===Secure connection (TLS)===
  
-For any MQTT application that is running over the internet (or Local Area Network accessable by general public) should use secure connections and password authentication. To enable TLS with a selfsigned certificate on the  mosquitto broker please follow this article.  +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:advanced_server_configuration:mqtt:mosquitto_tls|Add certificates for Mosquitto MQTT broker secure connections]]
Line 145: Line 172:
  
 If this section is missing in the config file, default settings is assumed for the broker.  If this section is missing in the config file, default settings is assumed for the broker. 
 +
 +
 <code> <code>
 mqtt: mqtt:
   defaultBroker:   defaultBroker:
     address: localhost  # Default is localhost     address: localhost  # Default is localhost
-    username: pixi   # Default is no username and password +    username: blocks  # Replace blocks with the username you have configured in the broker, leave empty if anonymous user is allowed.  
-    password: pixi +    password: pixi  # Replace pixi with the password setup with your user. 
-    encryption: false #Change to true if secure connection (tls) is available.+    encryption: false  # Set to true if secure connection (tls) is available. 
 +    port: 1883 # Default is 1883 if non-encypted and 8883 if encrypted
 </code> </code>
  
Line 168: Line 198:
  
 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.  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. 
-====3rd party tool MQTT Exlorer.====+====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.  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]] [[https://mqtt-explorer.com/|MQTT Explorer]]
  
-The two following screenshots show connection examples:+The two following screenshots show connection examples. 
  
 Without TLS encryption: Without TLS encryption:
Line 183: Line 214:
 {{:blocks:server:advanced_server_configuration:mqtt:skaermbild_2023-05-16_133403.png|}} {{:blocks:server:advanced_server_configuration:mqtt:skaermbild_2023-05-16_133403.png|}}
  
-After successfull connection the  $SYS/broker topic should appear. This is some statistics published by the broker itself.+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|}} {{:blocks:server:advanced_server_configuration:mqtt:skaermbild_2023-05-16_133551.png|}}