Set up 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

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

Before you begin, review the requirements for the host system, MQTT broker, and your MaintainX account. For an overview of how the OPA connects to MaintainX, see the Architecture Overview.

Create a Connector and an Access Token

To configure the OPA, you need an access token. The token authenticates the OPA with the MaintainX platform. For security purposes, every MQTT instance must have its own token.

warning

It's important to keep your token secure. Do not share it with unauthorized users.

Log into MaintainX as an Administrator.
From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
On the Integrations page, go to the Connectors tab.
Navigate to the MQTT connector, and select Connect. The MQTT dialog appears.
Select + Create New Instance.
Follow the steps to create a new MQTT instance until the Token appears.
Copy the Token and save it for later use.

note
The Token is only displayed once when you create the MQTT instance. If you lose the token for an MQTT instance, you can revoke it and create a new one. See Revoke and Regenerate an MQTT Access Token.

Configure the Host System

Log into the host system.
Create a workspace directory for the OPA. Then navigate to that directory.
```
mkdir -p ~/.maintainx/sensor-connect
cd ~/.maintainx/sensor-connect
```
In the workspace directory, create a configuration file named settings.json.

Edit the configuration file, and add the following information:

{
    "Integration": {
        "AccessToken": "{MaintainX-Connector-Token}"
    },
    "Mqtt": {
        "client": {
            "credentials": {
                "username": "{MQTT-Broker-Username}",
                "password": "{MQTT-Broker-Password}"
            },
            "tcpServer": {
                "server": "{MQTT-Broker-Host}",
                "port": {MQTT-Broker-Port}
            }
        }
    }
    // To declare which MQTT topics the agent listens to and how it
    // decodes their payloads, add an "MqttSubscriptionSettings" block.
    // See: Configure MQTT Subscriptions.
}

Definition of the fields in the settings.json file:

Line	Field	Type	Description
3	`MaintainX-Connector-Token`	String	Access token you copied when you created a new MQTT instance, used for authentication to the MaintainX platform.
8	`MQTT-Broker-Username`	String	Username to authenticate to your MQTT Broker.
9	`MQTT-Broker-Password`	String	Password to authenticate to your MQTT Broker.
12	`MQTT-Broker-Host`	String	Host URL of your MQTT Broker. This information can be found in your MQTT configuration.
13	`MQTT-Broker-Port`	Number	Port number of your MQTT Broker.

Install the MaintainX On-Premise Agent on the Host System

Log into the host system.
From the command line, download the Docker image for the OPA.
```
 docker pull maintainx/on-premise-agent:latest
```

Start the Docker container.

docker run -d --name on-premise-agent -v $HOME/.maintainx/sensor-connect:/config maintainx/on-premise-agent

Verify that the OPA is running and connected to your MQTT Broker and no error messages are displayed.
```
docker logs -f on-premise-agent
```
If the OPA is running and connected to your MQTT Broker, the following log messages are displayed:
```
Connected to MQTT broker host '{MQTT-Broker-Host}' on port '{MQTT-Broker-Port}'.
Listener started. Polling every 50 ms and uploading every 20 seconds
```

The OPA is now running and connected to your MQTT Broker. Sensor data from your MQTT broker will now be synchronized to the MaintainX platform.

Configure MQTT Subscriptions

By default, 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.

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 details on the configuration schema, the sensor naming rules, automatic type inference, and worked examples, see Configure MQTT Subscriptions.

Map Tags to Meters

After you set up the OPA, you can use smart tag mapping to connect your MQTT tags (topics) to meters in MaintainX.

The smart tag mapping system uses AI to analyze data tags you make available through your organization's MQTT connectors. For each tag, the system suggests a meter name, a unit of measurement, and an asset to assign the meter to. Using the tag management tool, you can:

View the MQTT tags that are available through your organization's MQTT connectors.
Review MaintainX's suggestions for mapping tags to assets in your organization.
Automatically create meters for your tags and associate them with the correct assets.

The tag mapping AI provides a confidence rating for each suggestion. You can edit any suggestion before creating the meter, and easily update mapped tags at any time.

For detailed instructions, see Smart Tag Mapping for OT Data.

info

The smart tag mapping system replaces the Auto Create Meters feature, which is no longer available. If you have existing OT connectors that connect to meters you configured using the Auto Create Meters feature, the smart tag mapping system won't affect them.

Update the On-Premise Agent

The process stops the current container and starts a new one with the updated image. During that time, no data is being sent to the MaintainX platform.

note

The configuration file settings.json isn't overwritten when you update the OPA. If you need to update the configuration, you'll need to update the file manually beforehand.

Pull the latest version of the OPA:

 docker pull maintainx/on-premise-agent:latest

From the command line, run the following command to stop the current container:
```
 docker stop on-premise-agent
```
Remove the current container:
```
 docker rm on-premise-agent
```

Start the new version of the OPA:

 docker run -d --name on-premise-agent -v $HOME/.maintainx/sensor-connect:/config -v $HOME/.maintainx/opa-certificates:/run/secrets maintainx/on-premise-agent:latest

note

If you made any additional changes when running the docker run command initially, you'll need to reapply them here again.

Verify that the OPA is running and connected to your MQTT Broker, and no error messages are displayed.
```
 docker logs -f on-premise-agent
```

Revoke and Regenerate an MQTT Access Token

The access token for an MQTT instance is only displayed once, when you first create the instance. If you lose the token, you can revoke it and generate a new one.

To revoke and regenerate a token:

Log into MaintainX as an Administrator.
From the sidebar, select Settings, and under ORGANIZATION SETTINGS, select Integrations.
On the Integrations page, go to the Connectors tab.
Navigate to the MQTT connector, and select Manage.
In the MQTT dialog, go to the Instances list and select the instance whose token you want to revoke.
In the Manage Instance dialog, select Revoke Token.

The instance's Status changes to Disconnected, and in the Token field shows Revoked.
Select Generate New Token.
Copy the new token from the Token field.

On the host system for the instance, you have to edit the configuration (settings.json) and replace the old token with the new one.

Troubleshooting

Agent unable to connect to MQTT Broker

This section provides some troubleshooting advice for when the OPA cannot connect to the MQTT broker.

Add your DNS Server to the Docker Container

If you're using the hostname or the fully qualified domain name (FQDN) for your MQTT broker, a Domain Name System (DNS) issue might be preventing the OPA from connecting to the MQTT broker.

You might be able to fix this by adding your DNS server to the Docker container. This issue is most commonly observed in Windows environments.

Add the --dns flag to the docker run command:

docker stop  on-premise-agent
docker rm on-premise-agent
docker run --dns={YourDnsIp} -d --name on-premise-agent -v $HOME/.maintainx/sensor-connect:/config -v $HOME/.maintainx/opa-certificates:/run/secrets maintainx/on-premise-agent:latest

tip

You can add --dns={YourDnsIp} for each DNS server you want to add.

Contact the MaintainX Support Team

If you continue to experience trouble with connecting the OPA to the MQTT broker, contact the MaintainX Support team.

Next Steps

Your OPA is connected to the broker, but it won't collect any data until you tell it which topics to listen to. Complete your setup with these steps:

Configure MQTT subscriptions: Declare the topics the OPA listens to and how it decodes their payloads into sensors. For more information, see Configure MQTT Subscriptions.
Set up TLS and certificate authentication: If your broker requires it, configure client certificate authentication or trust a private Certificate Authority. For more information, see TLS and Certificate Authentication.

Create a Connector and an Access Token​

Configure the Host System​

Install the MaintainX On-Premise Agent on the Host System​

Configure MQTT Subscriptions​

Map Tags to Meters​

Update the On-Premise Agent​

Revoke and Regenerate an MQTT Access Token​

Troubleshooting​

Agent unable to connect to MQTT Broker​

Add your DNS Server to the Docker Container​

Contact the MaintainX Support Team​

Next Steps​