Knowledge Base

MQTT is a standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth.

Table of contents

MQTT Settings

ComfortClick allows MQTT communication to use either an internal broker or an external broker.

When the Internal Broker is enabled, the ComfortClick server acts as the MQTT communication broker. Other MQTT devices, systems, or applications can then connect directly to the ComfortClick server to send and receive data.

This setup is useful when you want the ComfortClick server to manage MQTT communication locally, without requiring a separate external MQTT broker.

An External Broker can be used when MQTT communication is already handled by another broker in the network or cloud environment. communication.

Internal Broker

Enabled Broker Authentication can be enabled to provide additional security by password protecting the connection

Use Client ID restriction sets the minimum lenght of the Client's ID (e.g device name).
Store retained messages sets every new client connecting to the MQTT receives the last message sent to the MQTT.

Once internal broker is enabled, bOS will also display all the clients connected and sending values to our broker. Clients will show:

• Client ID which is basically the name of the client.

• Last Topic name of the last topic that the client was sending values.

• Last Message message or values that were sent from client to our broker (payload).

• Last Message Time provides exact date and time of the last message.

External Broker

Use internal broker = False, we will be using another machine as the MQTT broker so we need to set the correct ip/port and login credentials for MQTT. If external broker requires additional remote certification, use the Import functions to import the required certificates.

Import function will open file browsers, where we navigate to our certificate and import it into bOS for secure connection. Also make sure to enter the remote IP and port for External broker.

CA Certificate (Certificate Authority Certificate)
Purpose: Verifies the identity of the MQTT broker.

Details: This is a public certificate issued by a trusted Certificate Authority (CA). The MQTT client uses this to ensure it's connecting to a legitimate server.

File type: Often .crt or .pem

Client Certificate
Purpose: Identifies the client to the broker.

Details: This is a certificate issued to the client by a CA. The MQTT broker checks this certificate to authenticate the client.

Used in: Mutual TLS (mTLS), where both sides (client and broker) verify each other.

File type: Often .crt or .pem

Client Key
Purpose: Proves that the client certificate really belongs to the client.

Details: This is the private key corresponding to the client certificate. It's used to sign data and authenticate the client securely.

Important: Must be kept private and safe.

File type: Often .key or .pem

If remote broker server has additional SSL/TLS certificates, we need to enable SSL/TLS. Make sure you sort out the certificates on the server.

Once SSL/TLS function is enabled, certification options will open, allowing us to import certificates.

If the broker has set authentication, enable Broker Authentication to True and fill out the Username and Password below.

Step by step integration of a Shelly device that allows us to control and receive feedback to bOS is available in the video below:

Client Settings

Client allows us to publish and subscribe to broker and we can read status of the device and send command to the device.

• Client ID is a unique name for each individual client. No two client names can be alike.

• Keep alive is pinging the device every x seconds.

• Clean session is a flag that tells the broker how to handle the session state for a client — especially subscriptions and messages — when it connects or disconnects.

• MQTT Version is displaying current MQTT version used in this client/broker communication. (V500, V311, V310 or Unknown). 

• Birth Message is a special message that a client (often a device or service) sends automatically when it connects to the broker. For the Birth message we can set a specific topic and different Quality of Service types:
  At most once - Low importance; not guaranteed to arrive At least once - More reliable; might be delivered multiple times
  Exactly once - Highest reliability; never duplicated

• Birth message retain tells the MQTT broker to store the message and deliver it to new subscribers immediately — even if it was published earlier.

• Birth message payload  is the content the client sends to indicate it's alive and ready after connecting. It can be as simple or as detailed as you need, depending on the application.
  Last will message The Last Will and Testament (LWT) in MQTT is a predefined message that the broker will automatically publish if a client disconnects unexpectedly (e.g., power loss, crash, network failure).
  For the Last will message we can set a specific topic and different Quality of Service types: At most once - Low importance; not guaranteed to arrive At least once - More reliable; might be delivered multiple times
  Exactly once - Highest reliability; never duplicated
  Last will message retain will make Broker store the Last Will message. Any new subscribers to the topic immediately receive the message, ensururing offline status is visible even after it’s sent.

Subscriptions

Device specific topic that we want to subscribe to, to get the status of the device (this should be available in the manual of the device). Topic typically looks like: example/topic/light1

With topics, we can use wild charts (*,#) for example;

if we want to subscribe to all lights in a room we can use: example/*/light

if we want to subscribe to the first floor we can use: example/topic/#

Use Node Name function is by default enabled, using the same node topic as the node name in the configurator. Disabling this function will allow us to tweak the topic manually. This is specially useful when we're using groups, so we don't have to manually change the topics for each node. 

Full topic is always displayed and cannot be edited. It displays the current full topic of the node.

QoS : depending on the quality of the communication we can switch between values;

At most once - Best effort — may be lost

At least once - Guaranteed to arrive at least once

Exactly once - Guaranteed once only
Subscribe: once topic, QoS settings are set, we can enable subscribe, which will make client subscribe to the set topic.

Parser type: depending on the device, we set correct parser type so we get the correct information from the device.

Publish Messages

The ComfortClick MQTT Client and Internal Broker are not limited to subscribing to MQTT messages. They can also be used to publish messages to other MQTT devices, systems, or applications.

To publish an MQTT message, use the Publish Message function.

Publish Message Settings

• Topic defines where the MQTT message will be published. The topic is important because the receiving device or system must subscribe to the same topic to receive the message.

• Payload contains the message that will be sent. The payload can be a simple string, number, or other value format required by the receiving device.

  Dynamic values from the bOS configuration can also be included in the payload by using the % value option. This allows ComfortClick to publish live values from the configuration, such as temperature, status, mode, alarm state, or other datapoint values.

• Publish Trigger the Publish Trigger function can be used to automatically publish MQTT messages when specific events occur in the configuration.

This makes it possible to send MQTT messages automatically based on device changes, automation logic, alarms, schedules, or other system events.