Connect to the Evolo MQTT broker

The broker covers three use cases:

• Reading data: subscribe to values from the data points in the building.

• Control data points: write new values, such as a setpoint.

• Send data in: allow an external sender, such as a sensor vendor, to publish measurements directly into Evolo.

Before you begin

To get started, you’ll need the following:

• The gateway has been created and is online in Evolo.

• You have access to User → Integrations to create an MQTT key.

1. Enable MQTT on the gateway

1. Go to Configuration → Gateways.

2. Open the gateway you want to use.

3. Check the Enable MQTT box and click Save.

Evolo The gateway will now connect to the Evolo MQTT broker and mirror all data point values there. Also, make a note of the gateway key displayed on the gateway, for example, C5DM-YTZ1-GB71. It is used in all topics.

2. Create an MQTT key

1. Go to User → Integrations and select the MQTT tab.

2. Click Create New MQTT Client.

3. Enter a name and description.

4. Select permissions: Read MQTT to read data, Write MQTT to manage data points or send data.

5. Select which builds the key should apply to.

6. Click Create.

Copy the values that appear. The token is displayed only once.

3. Connection Details

These values are used in all MQTT clients, whether it’s MQTT Explorer, Node-RED, an SD system, or a sensor vendor’s own service:

4. Reading data

Requires "Read MQTT" access. The gateway publishes the value for each data point at:

evolo/<gateway-nøkkel>/tags/<datapunkt-id>/value

You can find the data point ID in the data point list at Evolo.

The values are sent as JSON numbers or true/false.

5. Manage data points

Requires the "Write MQTT" permission. Publish the new value to:

evolo/<gateway-nøkkel>/tags/<datapunkt-id>/write

The payload must be a plain JSON number or a Boolean value, without being wrapped in an object:

Topic: evolo/C5DM-YT2Z-GD71/tags/123/write 
Payload: 21.5 

Topic: evolo/C5DM-YT2Z-GD71/tags/456/write 
Payload: true

The data point must be writable on the interface to which it belongs, such as a setpoint on BACnet or Modbus. The write operation goes through the gateway and out to the field equipment in the same way as when you change the value in Evolo.

6. Sending Data from an External Transmitter

If you have a sensor vendor or a system that can publish MQTT messages on its own, it can send measurements directly into Evolo. In that case, the gateway does not need to connect to the vendor’s broker; the transmitter publishes to the Evolo MQTT broker, and the gateway retrieves the messages from there.

Requires an MQTT key with the “MQTT” access level for the network in which the gateway is located.

6.1 Add a device and interface in Evolo

Go to Configuration → Devices

1. Add a device that represents the sender, such as “Airthings” or “External Sensors.” Enter mqtt.evolo.no as the IP address/hostname. This field is required, but the gateway does not connect to it for this type of device; the data comes via the Evolo MQTT broker.

2. Add an interface to the device with the type “MQTT Incoming.” The interface does not require any broker settings.

A single interface can receive data from multiple physical devices. It is the topic for each data point that distinguishes them, so you do not need a separate device in Evolo for each sensor.

6.2 Determine the topics the sender should use

All messages to the gateway are published under the gateway’s own reception area:

evolo/<gateway-nøkkel>/inbound/<kilde>/...

You determine the part after inbound/ yourself, preferably using the vendor name and the device’s serial number, for example:

evolo/C5DM-YT2Z-GD71/inbound/airthings/2930123456/sample 
evolo/C5DM-YT2Z-GD71/inbound/kunde/rom109/vindu

The payload should be in JSON format. A single message can contain multiple measurements; Evolo extracts each measurement into its own data point.

6.3 Add Data Points

On the interface, add one data point for each measurement you want to include:

Multiple data points can use the same topic with different expressions. With the message {"temp": 21.7, "co2": 643}, one data point reads message.temp and another reads message.co2.

Data points can also be imported from Excel. Select Import → MQTT Inbound in the data point list and download the template from there.

6.4 Configure the Publisher

Set up the sender using the connection details from step 3 and the topics from 6.2. When the sender publishes, the values appear in the data points and are forwarded to logging, alerts, and dashboards as usual.

The values are also republished at evolo/<gateway-nøkkel>/tags/<id>/value, so you can verify the data flow using any MQTT client.

Troubleshooting