Creating an MQTT Bridge¶

On this page you will learn how to use the Kelvin Manager UI to create, edit, delete and control a Kelvin MQTT Bridge. There is a troubleshooting section at the end if you have any trouble.

What is MQTT ?¶

MQTT (Message Queue Telemetry Transport) is a lightweight network protocol to transport messages between devices. It uses a publish-subscribe architecture and usually runs over TCP/IP but can be used on many other communication protocols.

It has become a popular method to transfer continuous streams of data as it is very simple to implement and requires very low bandwidth. It also allows the clients who create information (publisher client) to be independent and not connected to clients who consume information (subscriber client).

The MQTT broker is the glue which manages the transfer of information between publishers and subscribers. MQTT clients will connect to the MQTT broker only.

What is a Kelvin MQTT Bridge ?¶

A Kelvin MQTT bridge is an MQTT subscriber client that consumes information generated from an MQTT publisher client. This is the orange colored MQTT client in figure 1 above. The information is stored directly in the Cloud Server as kelvin Metrics.

Each bridge created will access one MQTT broker through a Node. You can setup multiple bridges to access multiple MQTT brokers, through the same or different Node.

API Only Options¶

For the Kelvin Bridges there are some options that are only available through the Kelvin API.

Metric Guardrail¶

In some cases you may need to limit the metric value range. For each Kelvin Asset / Kelvin Metric pair you can set min / max limits.

    metrics_map:
      - name: demo-metric
        asset_name: roc_107
        access: RW
        data_type: raw.float32
        configuration:
          protocol_type: FLOAT
          polling_rate: 5
          address: 4.10.6
          min: 1.5
          max: 47.0

In this example the value coming in from the Bridge or being sent by the Control Change Manager will be limited between these values. Any values outside of this range will be ignored.

Deploy New MQTT Bridge¶

The MQTT bridge acts the same as an MQTT subscriber. It will connect to an MQTT broker, subscribe to topics and send the information directly to the Kelvin Metrics on the Cloud Server. You can also write data from Kelvin Metrics to a Topic on the MQTT Broker.

The Node acts as a gateway between the MQTT Bridges and the MQTT Brokers. All configurations to connect to the MQTT Broker are done in the MQTT Bridge deploy. You do not need to do any configuration on the Node.

Requirements¶

MQTT Broker¶

• An MQTT broker IP address or name (from your MQTT broker service provider or from your own setup PC)
• The MQTT broker's security credentials or certificates (from your MQTT broker service provider or from your own setup)
• A list of topics you want to subscribe to (Topics are defined by the client publishers. Usually this is done in the settings of the sensors or edge devices connecting to the broker)

If you use an MQTT service provider like CloudMQTT (https://www.cloudmqtt.com/), they will give you the security credentials to use.

Create a Node¶

A Kelvin Cluster must be setup with direct access to the brokers. This requires two steps;

1. Installing a computer at your premises to run the Kelvin Cluster software. The computer must be installed on the same local network as your MQTT brokers.
2. Creating a Kelvin Cluster on the computer in step 1. This will automatically connect the Kelvin Node to the Cloud Server. See here on how to install a Kelvin Node onto the computer.

Create a Metric¶

Every piece of data is connected to a Kelvin Metric. Normally each Kelvin Metric will represent one sensor or data point. It can also be a data point representing a calculated formulae of many data points.

Metrics for all the Topics must be created or exist before you can create an MQTT Bridge.

If you don't have any Metrics yet, then see here on how to create Kelvin Metrics and create them before proceeding.

Create Assets¶

Kelvin Assets are a group of Components, Parts and Sensors that make up a piece of equipment or machinery. It can be something as simple as a pump or as complex as a well.

Kelvin Assets will be composed of many Metrics that are the individual data that is collected by the Kelvin Bridges and stored in the Kelvin Core Manager.

When you create the bridge you can connect the Kelvin Asset to the Kelvin Metric to the Topic. One Kelvin Asset can have many Kelvin Metrics and thus Topics associated to it.

Firewalls¶

Ensure that there is a direct connection between the Node and all the MQTT brokers.

If not, then you will need to configure any firewalls or ip routing tables to guarantee communications between the Node and all MQTT brokers is not blocked.

Deploying with Kelvin Manager UI¶

Step 0: Starting the process¶

Go to the overview page on the Kelvin Manager UI. On the left hand side menu, select Bridges.

Then select Deploy Bridge.

Then select MQTT Protocol and click Next

Now you are ready to deploy a new MQTT bridge. Deploying a new bridge requires 6 steps;

1. Info - Selecting which Node to connect to and creating a unique name for your Kelvin Cluster
2. Topic and Payload Format - Defining the Topics and Payload format that will come from the MQTT Broker
3. Connection - Setting the MQTT Broker connection information
4. Security - Setting the security information to connect to the MQTT broker
5. Metric Mapping - Assigning the MQTT Topics to the Kelvin Metrics on the Cloud Server
6. Deploy - The Cloud Server will connect to the Node and send the MQTT Bridge parameters to it. The MQTT Bridge will automatically start after deployment.

We will now go through each step below and explain in detail every option you have.

Step 1: Info¶

Fill in the information (descriptions below) and click Next

Step 2 : Topic and Payload Format ¶

MQTT allows you to send any type of data in any format. To make sure Cloud Server can understand and interpret the payload data received, you will need to define the payload format.

Listed here will be all the types of message formats that have been defined. If you click on one of the formats you can see the definition of this payload.

Select the payload format that you will receive and then click Next

Payload QTV

The Topic format here is important to follow. You will define the Topics per Kelvin Metric in Step 5 - Metric Mappings.

The Payload format is important to follow. This defines how the data can be read and saved into the Kelvin Metrics in the Cloud Server.

Step 3 : Connection ¶

Fill in the information (descriptions below) and click Next

There are some advanced connection settings if you require. They are not mandatory.

Step 4 : Security ¶

From the drop down box, select a security option. Some options will have extra questions to answer. When finished, click Next

None : There is no security. You can proceed to the next step.

Certificate : You need to upload three certificates;

Credentials : Enter your login and password for your MQTT broker.

Step 5 : Metric Mapping ¶

This is the final step. You need to connect each Topic from the MQTT Broker with a Kelvin Asset and Kelvin Metric in the Cloud Server. One row represents one Topic.

Step 5.1 : Adding extra Rows ¶

If you run out of rows and need to add more Topics to Assets, you can add extra rows by clicking to the Add button at the bottom left corner.

Step 6 : Deploy ¶

When you are ready and feel good with the information entered, then click Deploy.

Step 7 : Confirm Deploy ¶

After you click Deploy, you will be asked to Confirm or Cancel the deployment.

Deploying with API ¶

By deploying with the API you can take advantage of the advanced features available.

We will follow our previous example and deploy an MQTT bridge.

First you need to define the basic information of the bridge.

"name": "demo-bridge",
"title": "Demo Bridge",
"acp_name": "node01",
"protocol": "mqtt"

Next you will need to provide a payload key based on the type of protocol you have selected. In our example we will be providing information for an MQTT protocol.

"payload": {
    "configuration": {
        "authentication": {
            "type": "none"
        },
        "connection": {
            "host": "d85585b5a2a04410883158f1cb48970e.s1.eu.hivemq.cloud",
            "port": 8883,
            "tls": true
        },
        "integration": "qtv"
    },
    "logging_level": "INFO",
    "metrics_map": [
        {
            "access": "RO",
            "asset_name": "tank-farm",
            "configuration": {
                "scale_multiplier": 1,
                "topic": "demo/temperature"
                "min": 1.5,
                "max": 47.0
            },
            "data_type": "raw.float64",
            "name": "air-conditioner-temperature"
        }
    ]
}

All the configuration keys are self explanatory. We will only highlight some notable keys below;

The full JSON should look like this;

{
    "name": "demo-bridge",
    "title": "Demo Bridge",
    "acp_name": "node01",
    "protocol": "mqtt"
    "payload": {
        "configuration": {
            "authentication": {
                "type": "none"
            },
            "connection": {
                "host": "d85585b5a2a04410883158f1cb48970e.s1.eu.hivemq.cloud",
                "port": 8883,
                "tls": true
            },
            "integration": "qtv"
        },
        "logging_level": "INFO",
        "metrics_map": [
            {
                "access": "RO",
                "asset_name": "tank-farm",
                "configuration": {
                    "scale_multiplier": 1,
                    "topic": "demo/temperature"
                    "min": 1.5,
                    "max": 47.0
                },
                "data_type": "raw.float64",
                "name": "air-conditioner-temperature"
            }
        ]
    }
}

Understanding Deploy Status ¶

When you click deploy, the Cloud Server will proceed to connect to the Kelvin Cluster you selected in Step 1 and deploy the MQTT Bridge App with the parameters you have defined here. The MQTT Bridge will then automatically start and connect to the MQTT Broker and start collecting data.

You can start, stop or restart the MQTT Bridge at anytime. Detailed instructions can be found later in this page.

Edit and Redeploy MQTT Bridge ¶

At any time you can reedit and change any parameter of the MQTT Bridge.

You can change any of the parameters while first deploying the MQTT Bridge. For example, you may want to change the Node, change the MQTT Client Publisher, update the security credentials or add some more Metrics Mapping.

To edit an existing MQTT Bridge, go to the overview page on the Kelvin Manager UI. On the left hand side menu, select Bridges.

Click on a MQTT Bridge name.

You will see the bridge details and all Assets being collected through this MQTT Bridge. Click on Edit Bridge.

Then you will go through the same steps when you first deployed the MQTT Bridge. The only difference is the current settings will already be entered. See Deploying a New MQTT Bridge for detailed instructions of each step. After you reach Step 6, come back here to continue.

When you are finished, you can click Deploy. You will be asked to confirm Redeploy.

Delete MQTT Bridge ¶

You can delete MQTT bridges that you no longer need.

To delete an existing MQTT Bridge, go to the overview page on the Kelvin Manager UI. On the left hand side menu, select Bridges.

Click on an MQTT Bridge name.

You will see the bridge details and all Assets being collected through this MQTT bridge. Click on Delete.

Start, Stop and Restart MQTT Bridge ¶

You can control each MQTT bridge from the dashboard. You may want to do that in cases where you want to stop listening to the Broker temporarily but don't want to delete the MQTT bridge.

In some cases when the Node temporarily loses connection to the cloud, you may need to restart the MQTT bridge once the connection is restored.

To start, stop or restart an existing MQTT Bridge, go to the overview page on the Kelvin Manager UI. On the left hand side menu, select Bridges.

Click on an MQTT Bridge name.

You will see the bridge details and all Kelvin Assets and Kelvin Metrics being collected through this MQTT bridge. On the top right hand corner you will see a button with one of three possible words; Stop, Start or Restart. This will depend on the current status of the MQTT Bridge.

Click the button to perform the action.

Troubleshooting¶

Deploying MQTT Bridge ¶

MQTT Broker ¶

Glossary of Terms ¶

Other Related Links¶

Interesting links related to MQTT Bridge

• Kelvin Bridges
• Kelvin Assets
• Kelvin Metrics

Credits¶

• MQTT Publish / Subscribe diagram from https://mqtt.org - 2021

Some icons and graphics used here are sourced from this kind artist;

• Some Icons made by Eucalyp from www.flaticon.com

Last Modified¶

Kelvin Documentation AI Support

Hi. My name is KevDocBot. How can I help you?

Send