Skip to main content

Configure MQTT Subscriptions

availability
Feature availability by platform, plan type, and user type
Platform:AvailableWebNot availableMobile
Plan Type:Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:Not availableRequesterNot availableFull UserAvailableAdministrator

Subscriptions you add to the MaintainX® On-Premise Agent (referred to as the OPA) define which MQTT topics the OPA listens to and how it turns their payloads into tags in MaintainX. Topic patterns, payload encoding, and ignored topics control which messages become tags and how the OPA reads their values.

Prerequisites​

  • MaintainX connector instance and access token: Created in MaintainX when you set up the integration. For more information, see Set Up the MQTT Integration.
  • OPA: A running OPA connected to your MQTT broker for your connector instance.

Identify Your MQTT Topics​

The OPA connects to your broker but doesn't subscribe to any topics until you add subscriptions. Before you do, gather the following information about the data you want to bring into MaintainX:

  • Topics: The topics your devices publish to. Use an MQTT client or your broker's administration tools to list them.
  • Payload format: Whether each topic carries a single value, such as 185.4, or a JSON object with several fields. This determines whether the subscription uses Raw or Json encoding.
  • Data types: Whether each value is a number, a string, or a boolean. If you prefer, you can set the type to Auto and let the OPA infer it.
  • Topics to exclude: Topics that match your patterns but carry data you don't need, such as heartbeat messages.

Custom subscriptions support the + wildcard for each topic level, so one subscription can cover many topics. For example, factory/line1/+ matches both factory/line1/oven_temp and factory/line1/door_open.

This article covers Custom subscriptions, which apply to any MQTT broker. For the other subscription types, see Subscription Types.

Supported Data Types​

The OPA supports the following data types for tags:

  • Number
  • String
  • Boolean

To let the OPA infer the data type from the first value it receives, set the type to Auto. A tag's data type is set when the tag is first created and isn't updated afterward. For more information, see Type Auto: Automatic Type Inference and Data Type Locking.

Add Subscriptions to the On-Premise Agent​

You declare subscriptions in the MqttSubscriptionSettings block of the settings.json file you created during setup. Each subscription pairs a topic pattern with rules that tell the OPA how to turn incoming payloads into tag readings.

To add subscriptions:

  1. Log in to the host system.

  2. Open the settings.json file in the OPA workspace directory (~/.maintainx/sensor-connect).

  3. At the top level of the file, alongside Integration and Mqtt, add an MqttSubscriptionSettings block with your subscription:

    {
      "MqttSubscriptionSettings": {
        "Version": "v1",
        "Subscriptions": [
          {
            "Topic": "factory/line1/+",
            "SubscriptionType": "Custom",
            "Payload": {
              "Encoding": "Raw",
              "Type": "Auto"
            }
          }
        ],
        "IgnoredTopics": []
      }
    }

    Definition of the main subscription fields:

    • Topic: The topic pattern to listen to, with optional + wildcards.
    • SubscriptionType: The subscription type. Set this to Custom.
    • Payload: The rules for decoding the payload, including its encoding (Raw or Json) and data type.
    • IgnoredTopics: The topic patterns to exclude from processing. Leave the array empty if you don't need to exclude any topics.

  4. Save the file.

  5. Restart the OPA container to apply the changes.

    docker restart on-premise-agent

  6. Verify that the OPA started and no error messages are displayed.

    docker logs -f on-premise-agent

    If a subscription is invalid, the OPA doesn't start, and the error message identifies the subscription by its index in the Subscriptions array. For more information, see Troubleshoot the MQTT Integration.

To add more subscriptions, repeat these steps. For details on payload decoding, type inference, tag naming, and wildcard rules, see the MQTT Subscription Reference.

Configuration Example​

The following example combines a Raw + Auto subscription on a wildcard topic, a multi-field Json subscription with dynamic units and a timestamp, and an IgnoredTopics entry:

{
  "Integration": {
    "AccessToken": "{MaintainX-Connector-Token}"
  },
  "Mqtt": {
    "client": {
      "credentials": {
        "username": "{MQTT-Broker-Username}",
        "password": "{MQTT-Broker-Password}"
      },
      "tcpServer": {
        "server": "{MQTT-Broker-Host}",
        "port": 8883
      },
      "tls": {
        "useTls": true
      }
    }
  },
  "MqttSubscriptionSettings": {
    "Version": "v1",
    "Subscriptions": [
      {
        "Topic": "factory/line1/+",
        "SubscriptionType": "Custom",
        "Description": "Per-tag scalar values from line 1",
        "Payload": {
          "Encoding": "Raw",
          "Type": "Auto"
        }
      },
      {
        "Topic": "plant/+/readings",
        "SubscriptionType": "Custom",
        "TimestampField": "ts",
        "Payload": {
          "Encoding": "Json",
          "Fields": [
            {
              "Path": "temperature",
              "Type": "Number",
              "FriendlyName": "Temperature",
              "UnitPath": "units.temperature"
            },
            {
              "Path": "pressure",
              "Type": "Number",
              "FriendlyName": "Pressure",
              "UnitPath": "units.pressure"
            },
            {
              "Path": "online",
              "Type": "Auto",
              "FriendlyName": "Online"
            }
          ]
        }
      }
    ],
    "IgnoredTopics": [
      "factory/line1/heartbeat"
    ]
  }
}

Map Tags to Meters​

At this point, MaintainX has tag data flowing in, but each tag still needs to be mapped to a meter before it can update readings, trigger work orders, or power automations. Smart tag mapping uses AI to suggest a meter, unit, and asset for each tag, so you don't have to configure every mapping manually.

For more information, see Map Tags to Meters.

Verify Data Is Flowing​

After you map your tags to meters, confirm that readings are reaching MaintainX.

  1. From the sidebar, select Meters.
  2. From the list, find a meter that's mapped to one of your MQTT tags.
  3. Select the meter to open it.
  4. In the Readings section, select See All Readings to confirm new readings are arriving.

Allow a few minutes after the OPA connects to your MQTT broker for the first readings to arrive. After that, readings arrive as tag values update in your MQTT broker. If no readings appear, see Not Seeing Data in MaintainX.