Connecting Your Machines Using MQTT

Note: If the machine that your team is looking to connect is a Lincoln Electric Machine please follow the instructions in the article Collecting Data from a Lincoln Electric machine using MQTT

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a messaging system that allows devices to send and receive data efficiently. It works with two key components:

• Clients – Devices that send (publish) or receive (subscribe) data.
• Brokers – The central hub that manages message delivery between clients.

In this setup, your machine will either:

1. Act as an MQTT broker (MachineMetrics connects directly to collect data).
2. Act as an MQTT client (You must set up an external broker for MachineMetrics and the machine to connect to).

Step 1: Setting Up MachineMetrics for MQTT Data Collection

1.1 Check Your Machine’s MQTT Support

First, determine how your machine handles MQTT:
✅ Has an MQTT broker – MachineMetrics can connect directly.
✅ Only acts as a client – You'll need a third-party MQTT broker.

If your machine only supports MQTT clients, set up an external broker (like Mosquitto or HiveMQ) before proceeding.

Step 2: Adding the machine to your Dashboard and Configuring the MQTT Connection

2.1 Adding the machine to your account and accessing the Data Collection Method

When adding a new machine that has an available MQTT client or Broker, select MQTT Data Collection Method from the dropdown menu. More details in the article Adding a New Machine to Your Account

2.2 Authentication (Optional)

Some brokers require a username and password for security. If needed, add them:

username: "your-username"
password: "your-password"

If no authentication is needed, you can skip this step.

2.3 Subscribing to MQTT Topics

Topics are like "channels" where machines send data. MachineMetrics subscribes to these topics to receive the data.

Option 1: Reading Raw Data

If the machine sends plain values (not JSON), use this format:

topics:
  machines/press10/status/running: is-running
  machines/press10/process/speed: press-speed
  machines/press10/process/program: program-name

• The left side (machines/press10/status/running) is the topic name.
• The right side (is-running) is the identifier used in MachineMetrics.

Option 2: Extracting Data from JSON Messages

If a topic’s message is a JSON object, multiple identifiers can be assigned from different parts of the JSON object. An example of these topics can be seen as the following.

key:
  json:
    identifier1: path.to.attribute.1
    identifier2: path.to.attribute.2
    identifier3: path.to.attribute.3

Example JSON message from the machine:

Assume there’s a topic machines/press10/partinfo which supplies a message value that looks like:

{ 
  "partnumber": 12345, 
  "start": "2024-10-31T12:34:00", 
  "material": "AA5052", 
  "count": { 
    "total": 200, 
    "good": 53, 
    "bad": 2 
  } 
}

To extract only the part number, material, and good part count, configure the script in the like this:

topics:
  machines/press10/partinfo:
    json:
      partnum: partnumber
      material: material
      partcount: count.good

Extended JSON Path Syntax

The Extended JSON Path Syntax is a specialized string format designed for identifying and navigating to a specific property within complex JSON objects, including those with nested objects and arrays of objects.

Syntax Overview:

• Regular Path String:

  • Example: machine.system.state navigates to the state property nested inside system and machine.

• Extended Find Notation:

  • Example: machines[id=102].location searches within machines for an object where the property id equals 102, then navigates to its location property.

Example: Basic Path

Given the following JSON body:

{
  "a": { 
    "b": { 
      "c": "test" 
    } 
  } 
}

The JSON path a.b.c will return the value test from the object.

Example: Search Within Array

Given the following JSON body:

{ 
  "g": { 
    "h": [
      { 
        "i": "j", 
        "k": "test-search-array" 
      }
    ]
  } 
}

The JSON path g.h[i=j].k will return the value test-search-array from the object.

The [i=j] performs a search within the array g.h, finding the first element where there’s a property named i equal to the string j. The remainder of the path, .k, continues resolving the search from within that element.

For another example of array search, given the following JSON body:

[ 
  { 
    "l": "m", 
    "n": [ 
      { 
        "o": "p", 
        "q": "test-search-array-root" 
      } 
    ] 
  } 
]

The JSON path [l=m].n[o=p].q will return the value test-search-array-root.

This example demonstrates multiple array searches within the JSON body, including the case where the outer-most element of the body is itself an array.

Example: Using an Array Index

Given the following JSON body:

[
  { 
    "r": { 
      "s": "test-index-array" 
    } 
  } 
]

The JSON path 0.r.s will return the value test-index-array.

A numerical index value can be used directly in the path to pick out the first, second, … nth entry of the array.

Step 3: Using the Data in MachineMetrics

Once MachineMetrics subscribes to topics, you can use the collected data:

1. Store values in variables for use in scripts.
2. Export selected data to MachineMetrics dashboards.

Example configuration to process values:

variables:
  execution:
    - state: is-running
      - ACTIVE: true
      - READY: false
data-items:
  - execution
  - press-speed
  - program-name

For more details on using a the configurating of an adapter using Adapter Scripts please review How to Get Started with a V2 Adapter Script

Final Notes

✅ MachineMetrics can connect to MQTT brokers or clients.
✅ Raw data or JSON extraction can be used.
✅ External brokers are needed if your machine only supports MQTT clients.

By following these steps, you can successfully connect your machine to MachineMetrics using MQTT for real-time data collection!