MQTT Addresses I/O – Integration with Node-RED and Home Assistant

This page describes step by step how third-party systems such as Node-RED and Home Assistant are connected to the uni-PRO controller via the function block MQTT Addresses I/O. The block sends the values of the variables (addresses) as MQTT messages to an MQTT broker and, in the other direction, accepts values that third-party systems send to the broker.

Important: For this function the controller must have an image version 3.034 or higher.

MQTT basics

MQTT is a simple messaging protocol for building and device automation. All participants connect to a central server, the broker:

• Topic: Each message is published under a name, the topic, e.g. "uniPRO/100/10/1". Topics are structured like paths using "/".
• Payload: The content of the message, here the value of the variable, e.g. "21.5".
• Publish / subscribe: One participant publishes messages, other participants subscribe to topics and receive the messages automatically.
• Wildcards: When subscribing, "+" can be used for one level and "#" for all following levels. "uniPRO/#" therefore receives all messages of the block.
• Retain: The broker remembers the last message of a topic and delivers it to new subscribers immediately. The "Retain" parameter of the block is active by default so that third-party systems know all values immediately after a restart.

Structure of the MQTT messages of the block

The topic is built from the parameter "Topic prefix" (default "uniPRO") and the address main group/middle group/sub group:

Only addresses of the main groups set in the parameter "Filter main group" are sent and received.

Configuring the block

1. Insert the function block "MQTT Addresses I/O" into the program.
2. Server type:
   • Internal: The MQTT broker integrated in the controller is used. No further setting is required. Third-party systems then connect to the IP address of the controller, port 1883, without user/password.
   • External: An external broker (e.g. Mosquitto) is used. Specify server, port and optionally user/password and TLS.
3. Filter main group: Specify the main groups of the variables to be transferred, several separated by semicolons, e.g. "100;101".
4. Leave "Update on start" and "Retain" activated so that third-party systems always have current values.

All parameters in detail: help MQTT Addresses I/O. To check the messages, the MQTT diagnosis in the Studio can be used (menu Diagnosis).

Node-RED

Node-RED is a graphical tool for building sequences (flows) from building blocks (nodes) using drag & drop. It runs e.g. on a Raspberry Pi, a server or in Docker. The installation is described here: nodered.org/docs/getting-started. After installation the editor is opened in the browser at "http://<IP-address>:1880".

The MQTT nodes

The MQTT nodes are a core part of Node-RED and do not need to be installed separately. They can be found in the palette on the left in the "network" category:

• mqtt in: Subscribes to a topic and passes each received message (msg.payload) on to the following nodes. This is used to receive values from uni-PRO.
• mqtt out: Publishes the incoming msg.payload under a topic. This is used to send values to uni-PRO.

If additional nodes are required (e.g. dashboards), they can be installed via menu (☰) → "Manage palette".

Creating the broker connection

Drag an "mqtt in" node into the flow and open it by double-clicking. Next to "Server", create a new mqtt-broker configuration using the pencil icon:

• Server: IP address of the broker. For the internal broker, enter the IP address of the controller.
• Port: 1883 (default).
• Security: Username/password only required if the broker demands authentication. The internal broker of the controller does not require a login.

The configuration only needs to be created once and can then be selected in all MQTT nodes.

Receiving values (mqtt in)

• Topic: "uniPRO/#" receives all variables of the block. A single variable is subscribed with the full topic, e.g. "uniPRO/100/10/1".
• QoS: 2 (default) can be kept.
• Output: "auto-detect" can be kept; the value then arrives as text in msg.payload, the topic in msg.topic.

Sending values (mqtt out)

• Topic: Full topic of the variable, e.g. "uniPRO/100/10/1". If the field is left empty, msg.topic of the incoming message is used.
• The value to be sent is passed as msg.payload, e.g. "21.5" or for bit variables "1"/"0", "on"/"off" or "true"/"false".

Example flow

1. Connect an "mqtt in" node (topic "uniPRO/#") to a "debug" node.
2. Connect an "inject" node (payload e.g. number 21.5) to an "mqtt out" node (topic "uniPRO/100/10/1").
3. Click "Deploy" at the top right. "connected" must appear below the MQTT nodes.
4. Received values appear in the debug sidebar (bug icon on the right). Clicking the inject node sends the value to uni-PRO.

Further examples: Node-RED cookbook MQTT, documentation: nodered.org/docs.

Home Assistant

Home Assistant is an open source software for home automation. The MQTT integration of Home Assistant is used for the connection.

MQTT broker

Home Assistant and the uni-PRO block must use the same broker. Two options:

• Internal broker of the controller: In the block select "Server type" = "Internal". In Home Assistant, enter the IP address of the controller as the broker, port 1883, without user/password.
• Mosquitto add-on: If the broker runs in Home Assistant (add-on "Mosquitto broker"), select "Server type" = "External" in the block and enter the IP address of Home Assistant, port 1883 and the credentials created in the add-on.

Setting up the MQTT integration

In Home Assistant: Settings → Devices & services → Add integration, search for "MQTT" and enter the connection data of the broker:

Automatic integration (auto discovery)

If the parameter "Home Assistant Auto Discovery" is activated in the block, the block sends a configuration message to Home Assistant for each variable. The variables then appear automatically as entities of type "number"; the name of the entity is the comment of the address:

Important: With auto discovery activated, the parameter "Topic prefix" must remain at the default value "uniPRO", because the automatically generated configuration uses these topics. Currently only entities of type "number" are created; all values are then transferred as numbers.

Manual integration (configuration.yaml)

Alternatively (or additionally, e.g. for switches), entities can be created manually in the file configuration.yaml. Example for a sensor and a switch:

mqtt:
  sensor:
    - name: "Living room temperature"
      state_topic: "uniPRO/100/10/1"
      unit_of_measurement: "°C"
  switch:
    - name: "Light living room"
      state_topic: "uniPRO/101/1/1"
      command_topic: "uniPRO/101/1/1"
      payload_on: "1"
      payload_off: "0"

payload_on/payload_off must match the parameter "Type bit variable" of the block (e.g. "on"/"off" instead of "1"/"0"). After changes to configuration.yaml, Home Assistant must be restarted. Details: Home Assistant MQTT documentation.

Testing

Under Settings → Devices & services → MQTT → Configure, Home Assistant offers a test tool: With "Listen to a topic" and the topic "uniPRO/#" all messages of the block are displayed. Via "Publish a packet" a value can be sent to an address for testing (topic e.g. "uniPRO/100/10/1", payload "21.5").

Troubleshooting tips

• The output "VB" of the block must be 1 (connected to the MQTT broker).
• In the Studio the MQTT diagnosis shows all messages sent and received by the broker.
• Check whether messages arrive using an "mqtt in" node with topic "#" in Node-RED or "Listen to a topic" in Home Assistant.
• Check whether port 1883 is reachable (firewall, network).
• The main group of the address must be included in the parameter "Filter main group".
• For sending and receiving it is recommended to use two blocks with different main groups (parameter "Mode").

Note: Node-RED, Home Assistant and Mosquitto are third-party products. The user is responsible for the installation, operation and security of this software; the linked documentation may change.