Overview

The MQTT Connector enables FIN to subscribe to and publish messages (point values) on topics hosted by an external MQTT broker. It’s designed for lightweight, event‑driven integrations where FIN either consumes device telemetry or publishes values/commands to other systems.

Auto‑discovery/learn is not supported, and history synchronization is not built‑in (use History Collected to persist history).

Supported protocol versions: MQTT 3.1.1 and 5.0.

Extension

In order to use the functionality, both MQTT and Task extensions must be enabled.

Follow the steps below to enable the extensions:

1. Select the App Launcher icon on the top left

2. Select the Settings tile under Advanced Apps

3. Select the Ext option to open up the extensions

4. Scroll down and find the following extensions: MQTTandTask

   • If the version number is green, this means that the extension is enabled

   • If the version number is red, this means that the extension is disabled

5. Select on the extension if it is disabled, this will open a drawer

6. Select on the Enable option

7. Refresh the page

Creating the connector

The MQTT connector can be added via the https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/770708276 → https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/770709304 under MQTT.

Broker Connectivity

The MQTT library supports connections to a broker using either the 3.1.1 or 5.0 version of the protocol. The protocol version to use can be configured on the connector using the mqttVersion tag.

You can specify the client identifier for the connector to use when connecting to the broker by setting the mqttClientId tag on the connector. If one is not specified, the connector will auto-generate one the first time it connects and save it on the connector.

TCP/IP

To connect to an MQTT broker over TCP/IP, use the mqtt scheme for a plaintext connection, or mqtts for a TLS connection to the broker. If you don't specify a port, then 1883 will be used for mqtt and 8883 will be used for mqtts.

Open

dis: "MQTT Conn" conn mqttConn uri: `mqtt://192.168.10.1/` mqttVersion: "v3.1.1" mqttClientId: "MqttTestClient"

Optional Connect Configuration

By default, the connection to the broker is opened with cleanSession=false (3.1.1) and cleanStart=false (5.0). You can set the mqttCleanSession: true tag on the connector to force the connection to use cleanSession/cleanStart.

By default, the session expiry interval is configured for "on-close", meaning the broker will retain client session information until the network connection is closed. Use the mqttSessionExpiryInterval tag on the connector to specify the duration for the session to linger after the connection is closed. A value of -1sec indicates that the session should never expire.

Web Sockets

To connect to an MQTT broker using web sockets, use the ws scheme for plaintext connections, and wss for secure web sockets.

Authentication

By default, the connector will attempt to connect to the MQTT broker anonymously.

If the broker requires a username and password, set the username tag on the connector and then call passwordSet() with the connectors id to set the password.

Steps:

1. Go to DB Builder → Connectors → MQTT.

2. Select the MQTT connector.

3. Click the “i” (info) icon to open the Property Editor.

4. Click the Add button (bottom-left).

5. Create a new string tag named username.

6. Set its value to the appropriate user name.

7. Copy the id value of the MQTT connector.

8. Click Apply to save the changes.

9. Navigate to Folio → Launch.

10. Run the query, passing:

    • The connector ID as the first parameter.

    • The password (in quotes) as the second parameter.

Some MQTT brokers require client certificate authentication over TLS. To configure client certificate authentication, set the mqttCertAlias tag to the alias in the crypto manager that contains your client's private key and certificate.

Some brokers also allow you to connect to the broker over the HTTPS port using Application-Layer Protocol Negotiation (ALPN). If your broker requires this type of connectivity, you must set the application protocol on the connector using the mqttAppProtocols tag. For example, to connect to an AWS IoT broker on the HTTPS port using ALPN you might set up a connector like this

Adding data points

As discovery is not supported, adding data points to the connector is a manual process. Each point has to be created and have a reference to the MQTT connector.

Steps to Create and Configure a Local Point for MQTT

1. In DB Builder, locate the MQTT connector and copy its Connector ID in the Property Editor.

   Open

   

2. While in DB Builder, create a new local point.

3. Set the Type property to one of the following (required for reading/writing):
   sensor, setpoint, or command.

   Open

   

4. Set the point to Connected by toggling the Connected switch.

5. In the Connector Ref field:

   • Select the MQTT connector from the dropdown or

   • Paste the connector ID (without the id == prefix).

6. Enter the MQTT topic you want to read from in the Cur Path field.

   Open

   

7. Click Save to save the point.

8. If the point should be writable:

   • Turn Writable on.

   • Enter the MQTT topic to publish to in the Write Path field.

     Open

     

9. If the point needs to read or write structured JSON payloads that include nested objects or arrays, add an additional string tag (e.g., pointName). Set the tag’s value to the JSON key that should be extracted or written.

   Open

   

10. Depending on the payload type, include the appropriate tags:
    raw (marker) — identifies raw‑value payload types
    json (marker) — identifies all JSON‑based payload types
    flatJson (boolean)

    • true → payload is a flat JSON structure

    • false → payload is a nested JSON structure

      Open

      

11. Once finished, save your changes and proceed to the section on setting up subscription and publishing.

Subscribe and Publish

To enable MQTT points to subscribe to incoming values and publish outgoing messages, the system uses two components: observables and tasks.

• Observables provide the asynchronous data stream for MQTT messages, generating updates whenever new data arrives.

• Tasks act as background workers that subscribe to these observables and asynchronously process the messages using Axon functions.

In the sections below, we’ll cover the steps required to set up points that read (subscribe) and write (publish) MQTT topics.

Payload structure type

MQTT supports multiple payload formats, so the method for subscribing and publishing to a data point depends on how the data is structured.
Below are three examples covering:

• Raw values

  79

  A payload that contains a single, simple value with no additional structure.

• Flat JSON payloads

  { "temp": 73, "humidity": 45, "co2": 400 }

  A JSON object containing key–value pairs.
  For instance, temp is the key and 73 is its value.

• Structured JSON payloads with nested objects or arrays
  These payloads are more complex and may contain nested objects, arrays, or a mix of both.
  Example 1:

  { "sensors": [ {"id": "temp", "value": 22.3, "unit": "C"}, {"id": "humidity", "value": 47.8, "unit": "%"}, {"id": "pressure", "value": 1012.4, "unit": "hPa"} ] }

  This structure includes:

  • A property named sensors (line 2), which is an array.

  • Each element in the array is an object containing fields like id, value, and unit.

  Example 2:

  { "location": "Building_A/Zone_3", "sensors": [ { "id": "temp_01", "type": "temperature", "value": 22.8, "unit": "°C", "setpoint": 23.0, "status": "normal" }, { "id": "humidity_02", "type": "humidity", "value": 47.2, "unit": "%", "setpoint": 50.0, "status": "normal" }, { "id": "co2_05", "type": "co2", "value": 812, "unit": "ppm", "threshold_high": 1200, "status": "elevated" } ], "device": { "deviceId": "hvac_sensor_node_17", "battery": 93, "rssi": -67 } }

  This structure includes:

  • A string property: location (line 2)

  • An array: sensors (line 3), containing multiple sensor objects

  • A nested object: device (line 29), with properties such as deviceId, battery, and rssi

Keep in mind that payloads may include additional information; however, when writing data, the system sends only the point name and value, not any extra properties. This means the original payload structure will be overridden.

While the functions can be customized for more complex scenarios, these examples keep the configuration simple for clarity.

Setting up subscription and publishing

MQTT supports different payload formats, and these examples help you subscribe to and publish each of the payload types described earlier. Depending on your use case, you may use some or all of them.

To get started, download the mqttRecs.trio file.

Open

How to Upload the Examples

1. Go to Folio → Launch.

2. Click the Upload button in the top-left corner.

3. Select the file (or drag and drop it).

4. Click OK to apply the upload.

After uploading, the file restores a set of Observables/Tasks and Functions for working with MQTT payloads.

It restores the following items:

Relationship between observables/tasks and their functions

The table below shows which function (if any) is paired with each observable/task, along with a short description of its purpose.

Configuring the Restored Items

After uploading, some properties must be customized to match your MQTT setup.

Observable / Task Properties

Depending on whether the task is for subscribing or publishing, the following three properties must be updated:

Property 1: obsMqttConnRef

• Set this to the ID of the MQTT connector.

• Required for read/subscribe tasks only.

Property 2: obsFilter

This property is used for writable (publish) tasks. It filters the points in the database to determine which ones are eligible for publishing.

In these examples, the filter depends on the following tags depending on the payload type, which must be present on the points:

• raw (marker) — identifies raw‑value payload types

• json (marker) — identifies all JSON‑based payload types

• flatJson (boolean)

  • true → payload is a flat JSON structure

  • false → payload is a nested JSON structure

Property 3: obsMqttTopic

Defines which MQTT topics the task will subscribe to.

• # subscribes to all topics.

• You may narrow this to a subset.
  Example:

  sensors/kitchen/#

  This limits subscriptions to topics under kitchen.

Function Configuration

In most cases, you should keep the default point filters. As long as your point setup matches the payload type, the functions will work without changes.

Functions that contain “Nested” in their name require manual updates to match your specific payload structure, such as:

• the array name

• the keys used for the point name and value

These names vary by device/vendor, so you must adjust them accordingly.

Updating Arrays and Keys in Nested JSON Functions

Below are the specific areas to update within each function.

Function: mqttReadNestedJsonFunc

Array Name

• Example uses "sensors"

• Appears 3 times (lines 5 (twice) & 7)

Key 1 – Point Name

• Example key: "id"

• Appears 2 times (line 14 twice)

Key 2 – Point Value

• Example key: "value"

• Appears 2 times (lines 15 and 16)

Function: mqttReadSensorNestedJsonFunc

Array Name

• "sensors" — appears 3 times (lines 5 (twice) & 7)

Key 1 – Point Name

• Example key: "id"

• Appears 2 times (line 14 twice)

Key 2 – Point Value

• Example key: "value"

• Appears 2 times (lines 15 and 16)

Function: mqttWriteNestedJsonFunc

Array Name

• "sensors" — appears 1 time (line 50)

Key 1 – Point Name

• "id" — appears 3 times (lines 31, 34, and 44)

Key 2 – Point Value

• "value" — appears 3 times (lines 31, 34, and 44)

Once these updates are complete, you can begin testing both subscription and publishing behavior.

Testing and troubleshooting

Tools:

• Eclipse Mosquitto - open-source, lightweight command line MQTT broker

• MQTT Explorer - MQTT client that provides a structured topic overview, and comes with a pre-configures public broker for testing