Set Up the MQTT Integration

availability

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

Setting up the MQTT integration involves installing the MaintainX® MQTT On-Premise Agent (referred to as the OPA), which connects your MQTT broker to the MaintainX platform, and creating a connector instance and access token.

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 MQTT Integration Architecture. If your broker requires a secure connection, see MQTT TLS and Certificate Authentication. After the OPA is running, you can configure which MQTT topics to monitor. For more information, see Configure MQTT Subscriptions. If you run into issues after setup, see Troubleshoot the MQTT Integration.

Create a Connector Instance and Access Token

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

danger

Keep your token secure. Don't share it with unauthorized users.

Log in to MaintainX as an Administrator.
From the sidebar, select Settings. Under Organization Settings, select Integrations.
On the Integrations page, go to the Connectors tab.
On the MQTT tile, select Connect (or Manage if you've already set up an integration). The MQTT dialog appears.
Select + Create New Instance.
In the Instance name field, enter a descriptive name (for example, Plant 1 Fan A).
Follow the steps to create a new connector instance until the Token appears.
Copy the Token and save it for later use.
Select Connect to finish provisioning the connector instance with the token you saved.
When the confirmation message appears, select Done to close the dialog.

note
The token is only displayed once when you create the connector instance. If you lose the token for a connector instance, you can revoke it and create a new one. For more information, see Revoke an Access Token.

After you create the connector instance, it appears in the Instances list with the status Waiting for Connection. It changes to Connected once the OPA connects to MaintainX.

Configure the Host System

Log in to 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 connector 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 in to the host system.
From the command line, download the MaintainX On-Premise Agent Docker image from Docker Hub.
```
 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. After you add subscriptions, sensor data from your MQTT broker is synchronized to the MaintainX platform. For more information, see Configure MQTT Subscriptions.

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
```

Manage Access Tokens

Each connector instance authenticates with MaintainX using an access token, which is displayed only once, when you first create the connector instance. If you lose the token or need to replace it, you can revoke it and generate a new one.

Revoke an Access Token

Revoke an access token if it's been lost, exposed to anyone outside your trusted network, or if you're rotating credentials as part of a security review.

warning

Running the OPA with an invalid or revoked token stops data flow until you generate a new token and update your configuration.

To revoke a token:

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

The connector instance's Status changes to Disconnected, and the Token field shows Revoked.

Regenerate an Access Token

Once you revoke a token, generate its replacement from the same Manage Instance dialog.

To regenerate a token:

Select Generate New Token.
Copy the new token from the Token field.
On the host system for the connector instance, edit the configuration (settings.json) and replace the old token with the new one.

Limitations

The OPA runs on a host system with Linux-based container support and a container runtime, such as Docker. For more information, see Host System.
Each connector instance connects one MQTT broker through one host system and one OPA. For more information, see Multiple Connector Instances.
The OPA reads data from your MQTT broker and doesn't write back to it. For more information, see Read-Only Access.
The OPA supports the Custom, Sparkplug, and Zigbee2MQTT subscription types. For more information, see Subscription Types.
Custom subscriptions decode payloads as Raw or Json and support the + wildcard in topic patterns. They don't support the # wildcard. For more information, see Wildcard Rules.
A tag's data type is set when the OPA creates it, and the OPA drops later payloads that have a different type. For more information, see Data Type Locking.
When more than one subscription matches the same topic, the OPA applies only the first matching subscription. For more information, see Overlapping Subscriptions.

Create a Connector Instance and Access Token​

Configure the Host System​

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

Update the On-Premise Agent​

Manage Access Tokens​

Revoke an Access Token​

Regenerate an Access Token​

Limitations​