Divus OPTIMA KNX MQTT Module User manual

OPTIMA MQTT Module Manual . 1
MQTT Module Manual
Version 3.0.0
REV01-20230221

OPTIMA MQTT Module Manual . 2
GENERAL INFORMATION
DIVUS GmbH
Pillhof 51
I-39057 Eppan (BZ) - Italy
Operating instructions, manuals and software are protected by copyright. All rights are reserved. Copying, multi-
plication, translation and conversion, either partially or as a whole, is not permitted. You are allowed to make a
single copy for backup purposes.
We reserve the right to make changes to the manual without prior notification.
We assume no responsibility for any errors or omissions that may appear in this document.
We do not assume liability for the flawlessness and correctness of the programs and data contained on the de-
livered discs.
You are always welcome to inform us of errors or make suggestions for improving the program.
The present agreement also applies to special appendices to the manual.
This manual can contain terms and descriptions, which improper use by third can harm the copyrights of the
author.
Please read the manual before beginning and keep the manual for later use.
The manual has been conceived and written for users who are experienced in the use of PCs and automation
technology.
CONVENTIONS
[KEYS]
Keys that are to be pressed by the user are given in square brackets, e.g. [CTRL] or [DEL]
COURIER
On-screen messages are given in the Courier font, e.g. C:\>
COURIER BOLD
Keyboard input to be made by the user are given in Courier bold, e.g. C:\>DIR
„…“
Names of buttons to be pressed, menus or other onscreen elements and product names are
given within double quotes. (e.g. “Configuration”).
PICTOGRAMS
In this manual, the following symbols are used to indicate particular text blocks.
Caution!
A dangerous situation may arise that may cause damage to material.
Hint
Hints and additional notes
New
New features

OPTIMA MQTT Module Manual . 3
INDEX:
1OVERVIEW ____________________________________________________________________________________4
1.1 FOREWORD ________________________________________________________________________________4
1.2 PURPOSE OF THIS DOCUMENT _______________________________________________________________5
1.3 PREREAUISITES _____________________________________________________________________________ 6
2MQTT BROKER _________________________________________________________________________________7
2.1 FOREWORD ________________________________________________________________________________7
2.2 BROKER-EINSTELLUNGEN____________________________________________________________________7
2.3 USERS _____________________________________________________________________________________8
3MQTT CLIENT __________________________________________________________________________________9
3.1 FOREWORD ________________________________________________________________________________9
3.2 NEW CONNECTION_________________________________________________________________________10
3.3 ASSOCIATION OF OBJECTS _________________________________________________________________12
3.4 INTERNAL CONNECTION ____________________________________________________________________13
3.5 M2M CONNECTION ________________________________________________________________________14
3.6 NOTES ____________________________________________________________________________________16

OPTIMA MQTT Module Manual . 4
1Overview
1.1 FOREWORD
DIVUS KNX SERVER can connect as a client to one or more MQTT brokers to publish them and receive data in
real time. This function is useful for interacting with devices or systems running on cloud services other than
those of DIVUS.
.
In addition, the KNX SERVER can in turn work as an MQTT broker and thus fulfils the role of a "star centre" for
communication with the devices of the local network with this exchange protocol:

OPTIMA MQTT Module Manual . 5
This prerogative can also be used to allow two or more KNX SERVERs to communicate with each other as shown
in the following diagram:
1.2 PURPOSE OF THIS DOCUMENT
This manual contains all necessary information to activate and configure the MQTT broker integrated in KNX
SERVER; chapter 3 is dedicated to this topic.
Chapter 4, on the other hand, illustrates how to configure and use KNX SERVER as a client for an MQTT broker
and how objects can be linked in such a way that when their state changes, they are published (to inform the
MQTT service of the state change) and vice versa, they are commanded by the broker when receiving a data
packet.
In particular, it is shown how to point the client to its own integrated broker or to the broker of another KNX
SERVER in the network.
The manual is primarily aimed at installers, but can also be a good guide for end users interested in personalising
the management of their own smart home system.
It assumes a good knowledge of the MQTT protocol and the devices to be managed and controlled by it, as well
as of OPTIMA; many sections of this document refer to general concepts that can be deepened in the following
manual:
KNX SERVER - Administration Manual

OPTIMA MQTT Module Manual . 6
1.3 PREREQUISITES
To integrate a KNX SERVER with one or more MQTT brokers, you must have the following
•A KNX SERVER 3 that has been updated to version 3.0.0 or higher.
To use the integrated MQTT broker on the device, you need:
•A KNX SERVER 3 that has been updated to version 3.0.0 or higher
Older server versions and other devices of the OPTIMA family do not support the MQTT module!

OPTIMA MQTT Module Manual . 7
2MQTT Broker
2.1 FOREWORD
The KNX SERVER 3 offers an MQTT broker, which can be used to connect not only the web server itself, but also
third-party devices that support this protocol or other KNX SERVERs, provided they are located in the same LAN.
This chapter explains how to set up the integrated MQTT broker of the KNX SERVER; after the described
procedures have been performed, it is typically necessary to activate the MQTT broker:
•Configure third-party devices to operate the broker.
•Configure the KNX SERVER itself to allow its objects to interact with the broker (internal client
connection).
•Configure other KNX SERVERs to point to the Broker.
For the first point, you need to refer to the documentation of the devices you want to integrate with the Broker.
The second and third point are described in the next chapter in reverse order; if you do not use the integrated
Broker of the KNX SERVER, but only want to configure a connection to an external Broker, please jump directly to
the next chapter.
2.2 BROKER SETTINGS
Select the item
TECHNOLOGIES > MQTT-BROKER > BROKER SETTINGS
to set the following:
EXECUTE AT
STARTUP
Activate this option to start the broker when the system is booted up.
AUTHENTICATION
Activate this option to check the credentials of the connecting clients. A highly
recommended option.
To start the broker, press the START button; after each further change, you must press UPDATE so that it is
correctly applied.

OPTIMA MQTT Module Manual . 8
2.3 USERS
If authentication is enabled, a user must be set up for each client device that is to connect to the Broker.
You must also prepare login information for the KNX SERVER itself when it connects to your Broker, as described
in more detail in the following chapter.
Pressing the ADD button inserts a new line in the User section; specify for each new line:
NAME
Description of the user within the system
USERNAME
User name to be used by the MQTT client
PASSWORD
Password to be used by the MQTT client
ENABLE
Deselect to keep the user's credentials in memory but not allow him to connect
Press Refresh after each change in the user list.
Once the users are set up and the Broker has been started, follow the instructions in the next chapter to configure
the client connection.

OPTIMA MQTT Module Manual . 9
3MQTT Client
3.1 FOREWORD
KNX SERVER allows the connection to more than one MQTT broker at the same time; it is advisable to keep the
number of such connections as low as possible in order not to overload the system resources.
One or more objects can be assigned to each MQTT connection:
•when a value is received via MQTT, it is passed as a command to the object
•Conversely, if the state of the object changes, its value is sent to the broker via MQTT.
Two topics can be assigned to each of the objects connected to the link, i.e. the communication channels through
which the KNX SERVER exchanges information with the broker; more information about MQTT topics can be found
in the specifications of this protocol and in the documentation widely available on the Internet.
The report topic is used by KNX SERVER to send the status of objects when it changes
:

OPTIMA MQTT Module Manual . 10
Conversely, when the KNX SERVER receives a value in the command topic, it executes it as a command for
objects:
In both cases, KNX SERVER expects numeric values to be exchanged via Topics, using the dot as decimal separator
(if they are not integer values); other formats, such as JSON, are not expected.
At least one command or report topic must be specified for each object. It is of course possible to specify both.
The use of the same topic for command and report is strongly discouraged, as this can create loops!
A KNX SERVER can take over the role of the MQTT broker, as described in the previous chapter. In order to
connect to the integrated broker, a connection must be established in any case, but according to a simplified
procedure, which is described in more detail below.
3.2 NEW CONNECTION
To create a new connection, expand
TECHNOLOGIES > MQTT-CLIENT
in the Administration side menu and press the (+) button in the toolbar. Once the new connection is created,
access its tab to set the parameters. A window like the one in the following figure is displayed:

OPTIMA MQTT Module Manual . 11
Enter the following information:
NAME
Identifies the connection within the project
BROKER SOURCE
Specify "Use external broker" to connect to a service on the Internet or to another
device on the LAN.
Otherwise, select "Use integrated broker " to connect to the internal broker of the
KNX SERVER (see next section for details).
MQTT BROKER
ADDRESS
MQTT broker Internet domain, without port and path
IP PORT
Communication port. As a rule, the following ports are used:
•1883: Unencrypted MQTT communication
•8883: MQTT communication encrypted with SSL
UNIQUE CLIENT ID
Enter a wording (no spaces or special characters recommended) that uniquely
identifies the KNX SERVER Client for the broker.
Depending on the MQTT service used, there may be restrictions on this wording or
it may be provided directly by the service.
SSL ENCRYPTION
Enable if communication is SSL protected

OPTIMA MQTT Module Manual . 12
AUTHENTICATION
Enable if the service requires authentication
USERNAME
PASSWORD
Access data of the service
ECHO TIMEOUT
Time interval in seconds for the anti-echo function. The default value is set to 10
seconds. Normally it is not necessary to adjust this parameter.
When all the data has been entered, press START to start communicating with the broker; if the data and
credentials are correct, after a few seconds the CONNECTION STATUS should change to CONNECTED. Now you
are ready to link objects to the connection.
3.3 ASSOCIATION OF OBJECTS
Drag and drop the objects you want to connect to the service into the Assigned Objects section; for each of these
objects, at least one of the following parameters must be specified:
COMMAND TOPIC
Name or path of the topic to which commands are to be received.
REPORT TOPIC
Name or path of the topic in which status changes are to be published.
Via the selector in the STATE column, it is possible to control the object directly to check in real time whether the
MQTT communication is correct:
The following screenshot shows an example of a test MQTT client software with which it is possible to subscribe
to the same broker and read/write the same Topics and thus check the correct communication of the KNX
SERVER:

OPTIMA MQTT Module Manual . 13
Before performing a test with the KNX SERVER, you should check the correct configuration and functionality of
the broker. For this purpose, other known devices can be used or two instances of a test MQTT client software
can be used, which write and receive each other on command and report topics.
When the expected operation is verified, one can proceed with the configuration of the KNX SERVER and perform
the corresponding tests in the real environment.
3.4 INTERNAL CONNECTION
To connect to the internal KNX SERVER broker, select "Use integrated broker" in the above configuration of the
client connection; in this case, it is not necessary to enter all the fields normally required and it is possible to
select the user from a drop-down menu (instead of entering it manually). For security reasons, it is still necessary
to enter the password.
.

OPTIMA MQTT Module Manual . 14
3.5 M2M CONNECTION
It is possible to use the MQTT protocol to realise a bidirectional machine-to-machine communication between
several KNX Servers as long as they are all connected to the same network.
It must first be determined which KNX SERVER is to act as the "master" and the integrated MQTT broker must be
activated on it.
Then the MQTT client connections must be configured as follows:
•On the same KNX SERVER, configure an "integrated broker" connection by selecting one of the
previously set up users.
•On the other KNX Servers, establish a generic connection, specify the IP address of the master and
manually enter the user to be used
For each KNX SERVER, including the master, a separate user must be set up and a unique client ID assigned.
•To control an object of another server from a KNX SERVER, proceed as follows:
•In the KNX SERVERto be controlled, drag the object (e.g. KNX) into the Assigned Objects area, arbitrarily
deciding the topic for Command and for Report.
oIn other KNX Servers, create a virtual object with the same graphical representation and drag
it into the corresponding MQTT client connection by...
ousing as command topic the one that is responsible for the report in the other server

OPTIMA MQTT Module Manual . 15
In other words, the topics must be crossed between the object to be commanded and the synchronised object
on the other KNX-SERVER, as shown in the figure.

OPTIMA MQTT Module Manual . 16
3.6 NOTES

OPTIMA MQTT Module Manual . 17