Skip to main content

MQTT Integration Architecture

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® MQTT On-Premise Agent (referred to as the OPA) connects an MQTT broker to MaintainX over a secure architecture. It's built on a set of design principles and core services, with a security model designed for reliable tag data streaming.

Design Principles​

Non-Intrusive Design​

The OPA is designed to minimize its impact on your MQTT broker and operational technology (OT) environment:

  • Read-only subscriber: The OPA listens to and processes messages from your broker without writing back to it. For more information, see Read-Only Access.
  • Existing infrastructure: Your broker, PLCs, and publishing clients keep working as they do today, with no changes to how they publish data.
  • Containerized deployment: The OPA runs in a container on a host system in your network. For more information, see Host System.

Flexible Data Ingestion​

The OPA adapts to the way you're already publishing your data:

  • Multiple topic structures: The OPA reads flat (custom) MQTT topics, Sparkplug B, and Zigbee2MQTT. For more information, see Subscription Types.
  • Multiple payload formats: Raw payloads carry a single value, and JSON payloads can supply one or more fields. For more information, see Payload Encoding.
  • Automatic type detection: The OPA can infer each tag's data type from the payload. For more information, see Automatic Type Inference.

Subscription-Based Collection​

You decide exactly which data reaches MaintainX:

  • Explicit subscriptions: The OPA connects to your broker but doesn't subscribe to any topics until you declare them. For more information, see Subscription.
  • Wildcard patterns: Topic patterns with + wildcards let a single subscription cover many similar topics. For more information, see Configure MQTT Subscriptions.

Isolated Connector Instances​

Each MQTT connector instance operates independently of the others:

  • Dedicated components: Each connector instance has its own MQTT broker, host system, and OPA. For more information, see Multiple Connector Instances.
  • Unique access tokens: Each OPA authenticates with MaintainX using the access token for its own connector instance.

Core Services​

The MQTT integration consists of two core services that work together to reliably stream data from your MQTT broker to MaintainX: the OPA on your host system and the MQTT connector instance in the MaintainX application.

Connection flow from an MQTT broker through the On-Premise Agent to a MaintainX connector instance

On-Premise Agent​

You install the OPA on a host system in your network. Your MQTT broker sends data to the OPA, which processes the messages according to the subscriptions and settings in its configuration file.

MQTT Connector Instance​

The OPA connects to a connector instance in the MaintainX application using a unique access token.

Multiple Connector Instances​

You can create multiple connector instances in MaintainX. In that case, each connector instance requires its own:

  • MQTT broker
  • Host system
  • OPA
Multiple On-Premise Agent instances, each connecting its own MQTT broker to a separate MaintainX connector instance

Security​

Read-Only Access​

The OPA operates in read-only mode. It only subscribes to and processes messages from your MQTT broker, and never writes back to it.

Secure Outbound Communication​

The OPA communicates with MaintainX over a secure, outbound HTTPS connection. Outgoing traffic from the host system reaches https://agent.maintainx.com/ on port 443.

Network requirements:

ParameterValue
ProtocolHTTPS (TLS)
DirectionOutbound only
Destination URLhttps://agent.maintainx.com/
Port443

Token Authentication​

Every request from the OPA to MaintainX is authenticated using the access token. The token is generated in MaintainX when you create a connector instance and is unique to that connector instance. MaintainX validates the token on every incoming request. You store the token in the settings.json configuration file on the OPA's host system.

The token is displayed only once at creation time. If a token is lost or compromised, it can be revoked and replaced without affecting other connector instances. For instructions, see Revoke an Access Token.

Broker Connection Security​

By default, the OPA uses a secure Transport Layer Security (TLS) connection to communicate with the MQTT broker, and only trusts certificates signed by recognized authorities. You can also configure client certificate authentication and add your own Certificate Authority (CA) certificate. For more information, see MQTT TLS and Certificate Authentication.