Skip to main content

About the MQTT On-Premise Agent

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

The MaintainX® On-Premise Agent (OPA) connects an MQTT broker to the MaintainX platform so you can see data from your connected sensors in the MaintainX application.

MQTT Connector Overview
MQTT Connector Overview

Requirements​

Host System​

  • Operating system: Any operating system with support for Linux-based containers.
  • Software: Container runtime such as Docker installed. For more information, see the Docker Installation Guide.
  • Network: Ensure that the outgoing network traffic from the host system can access https://agent.maintainx.com/ on port 443.

MQTT Broker​

  • A messaging broker that uses the MQTT protocol. It receives and publishes messages from different systems such as Sparkplug, Majik or AWS IoT Core.
  • Network: Ensure that the MQTT Broker is accessible from the host system.

MQTT Clients​

MaintainX Account​

  • Integration Connectors permissions. Please contact your organization's Administrator to request access to the OT Data Connectors feature.

Key Concepts​

The following concepts are referenced across the MQTT documentation. Understanding these terms will help you through the setup guide, subscription configuration, and troubleshooting.

Subscriptions​

The OPA connects to your broker but doesn't subscribe to any topics until you tell it which ones to listen to. You declare subscriptions in the MqttSubscriptionSettings block of settings.json. Each subscription pairs an MQTT topic pattern with rules that tell the OPA how to turn incoming payloads into sensor readings.

For each subscription, you choose:

  • The MQTT topic pattern (with optional + wildcards).
  • How to decode the payload: Raw (one value per topic) or Json (extract one or more fields).
  • The data type for each value: explicit (Number, String, Boolean) or Auto to let the OPA infer the type from the payload.

For the full configuration schema and worked examples, see Configure MQTT Subscriptions.

Subscription Types​

The OPA supports the following subscription types:

SubscriptionTypeWhen to Use
CustomAny MQTT broker. You control topic patterns, payload decoding, and field mapping.
SparkplugBrokers using the Sparkplug B specification.
Zigbee2MQTTBrokers fronting a Zigbee2MQTT bridge.

The Custom type is the most flexible and applies to any MQTT broker. For details, see Configure MQTT Subscriptions.

Payload Encoding​

Each subscription decodes its payload as either Raw (the entire payload is a single scalar value) or Json (the payload is a JSON object from which the OPA extracts one or more fields). For details, see Payload Encoding.

Automatic Type Inference​

Type: "Auto" lets the OPA decide a sensor's data type from the payload itself, instead of forcing you to declare it up front. It works for both Raw and Json encodings. For details, see Type Auto: Automatic Type Inference.

Data Type Locking​

A sensor's data type is set on first creation and never updated afterward. If a later payload for an existing sensor has a different type than the one stored at creation, the OPA drops the payload. For details, see Data Type Locking.

Sensor Naming​

The OPA derives each sensor's name from a combination of the received topic and the field configuration. For the full set of rules, see the Sensor Naming Matrix.

Resources​