MQTT Connectivity

Adapter script required — MQTT will not work without topic / payload mapping

Creating an MQTT machine in MachineMetrics does not automatically turn broker messages into dashboards and timelines. You must add a Transform Adapter Script that maps topics, JSON paths, and fields in your payloads to MachineMetrics data items. Without that script, subscriptions may succeed but no structured machine data will appear — customers often report “it doesn’t work” when this step was skipped.

Payload mapping and an adapter script are mandatory before you will see data. See Examples on this page for sample configurations. Contact support@machinemetrics.com if you need more help.

Overview

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for efficient data exchange in IoT and industrial environments. MachineMetrics can connect to machines that publish data via MQTT, enabling real-time data collection from a wide variety of equipment.

Key Features:

Lightweight and efficient messaging protocol
Publish/subscribe architecture
Support for both MQTT brokers and clients
JSON and raw data extraction
Ideal for custom integrations and non-standard equipment

Common Use Cases:

Lincoln Electric welding machines
Custom machine integrations
IoT sensor networks
PLC-based systems with MQTT output
Machines with proprietary controls offering MQTT

What is MQTT

MQTT is a messaging system that enables devices to send and receive data efficiently using a publish/subscribe model.

Key Components:

1. Clients

Devices that publish (send) data
Devices that subscribe (receive) data
MachineMetrics acts as a subscriber

2. Brokers

Central hub that manages message delivery between clients
Routes messages from publishers to subscribers
Can be on the machine itself or external

3. Topics

Named channels where messages are published
Hierarchical structure (e.g., machines/press10/status/running)
Subscribers can filter by topic patterns

How It Works:

Machine (Publisher) → Broker → MachineMetrics (Subscriber)

Machine → External Broker ← MachineMetrics

Two Setup Scenarios:

Scenario 1: Machine has MQTT Broker

MachineMetrics connects directly to the machine
Machine acts as both publisher and broker
Simpler setup, no external infrastructure needed

Scenario 2: Machine is MQTT Client Only

Requires an external MQTT broker (Mosquitto, HiveMQ, etc.)
Machine publishes to external broker
MachineMetrics subscribes to external broker
More complex but supports multiple machines on one broker

When to Use MQTT

Use MQTT when:

✅ Machine has built-in MQTT support
✅ Custom data integration required
✅ Standard protocols (MTConnect, FOCAS, etc.) not available
✅ Connecting Lincoln Electric welding machines
✅ Integrating IoT sensors or custom controllers
✅ Machine publishes data in JSON format
✅ You need flexible, lightweight communication

Do NOT use MQTT when:

❌ Machine supports standard protocols (use MTConnect, FOCAS, OPC-UA, etc. instead)
❌ You need bidirectional control (MQTT integration is data collection only)
❌ Machine has no MQTT capability

Prerequisites

Before setting up MQTT connectivity, ensure you have:

Hardware Requirements:

Machine with MQTT broker or client capability
MachineMetrics Edge device on same network
Network connectivity between machine and Edge

Network Requirements:

Machine IP address (static or reserved DHCP)
MQTT broker IP address (if using external broker)
Default MQTT port: 1883 (unencrypted) or 8883 (TLS)
Network firewall rules allowing MQTT traffic

Machine Requirements:

MQTT enabled on machine control
Knowledge of MQTT topics the machine publishes to
Authentication credentials (if required)
Documentation of data format (JSON structure, raw values, etc.)

Optional: External MQTT Broker

If machine only supports MQTT client mode, set up an external broker:

Popular MQTT Brokers:

Mosquitto (open source, widely used)
HiveMQ (enterprise features)
EMQX (scalable, cloud or on-premise)
AWS IoT Core (cloud-based)

MQTT Broker vs Client Setup

Check Your Machine's MQTT Support

Determine how your machine implements MQTT:

Option 1: Machine Has MQTT Broker ✅

MachineMetrics can connect directly
No external infrastructure needed
Configure MachineMetrics to connect to machine's IP

Option 2: Machine is MQTT Client Only ⚠️

Requires external MQTT broker
Set up broker (Mosquitto, HiveMQ, etc.) first
Configure machine to publish to broker
Configure MachineMetrics to subscribe to broker

Setting Up External MQTT Broker (If Needed)

If your machine only acts as an MQTT client, follow these steps:

Step 1: Install Mosquitto (Linux Example)

sudo apt-get update
sudo apt-get install mosquitto mosquitto-clients

Step 2: Configure Mosquitto

Edit /etc/mosquitto/mosquitto.conf:

listener 1883
allow_anonymous true  # Or configure authentication

Step 3: Start Mosquitto

sudo systemctl start mosquitto
sudo systemctl enable mosquitto

Step 4: Test Broker

Subscribe to test topic:

mosquitto_sub -h localhost -t test/topic

Publish test message (in another terminal):

mosquitto_pub -h localhost -t test/topic -m "Hello MQTT"

Step 5: Configure Machine

Configure your machine to publish to the broker's IP address and port 1883.

Adding Machine in MachineMetrics

Basic Configuration

Step 1: Add Machine

Log into MachineMetrics at app.machinemetrics.com
Navigate to Assets → Machines
Click Add Machine
Enter machine details:
- Name: (e.g., "Welding-Station-01", "Press-10")
- Type: (Select appropriate machine type)
Click Next

Step 2: Select MQTT Data Collection Method

In Data Collection Method, select MQTT
If not visible, select Custom Adapter and enter mqtt as adapter type

Step 3: Configure Connection

Enter the basic MQTT connection configuration:

version: 2

topics: {}  # Topics configuration (see below)

Note: The connection to the MQTT broker is configured in the machine settings UI (IP address and port). The adapter script focuses on topic subscriptions and data extraction.

Authentication Setup

If your MQTT broker requires authentication, add credentials at the top level:

version: 2
username: "mqtt-user"
password: "secure-password"

topics: {}

If no authentication is required, omit the username and password fields.

Subscribing to Topics

Topics are channels where machines publish data. MachineMetrics subscribes to these topics to receive data.

Topic Structure:

Topics typically follow a hierarchical structure:

machines/press10/status/running
machines/press10/process/speed
machines/press10/process/program

Components:

machines - Category
press10 - Machine identifier
status or process - Data category
running, speed, program - Specific data point

Data Extraction Methods

Reading Raw Data

If the machine publishes plain values (not JSON), map topics directly to identifiers:

Example Configuration:

version: 2

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

Format:

topic-name: identifier

Left side: MQTT topic path
Right side: Identifier used in MachineMetrics

What This Does:

Subscribe to machines/press10/status/running
Store value as is-running
Value can be used in scripts and exported as data item

Extracting JSON Data

If a topic publishes JSON messages, extract specific fields using JSON paths.

Example: JSON Message from Machine

Topic: machines/press10/partinfo

Message:

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

Configuration to Extract Specific Fields:

version: 2

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

Format:

topic-name:
  json:
    identifier1: json.path.1
    identifier2: json.path.2
    identifier3: json.path.3

Left side (identifier): Name used in MachineMetrics
Right side (JSON path): Path to field in JSON message

What This Does:

Subscribe to machines/press10/partinfo
Extract partnumber → store as partnum
Extract material → store as material
Extract count.good → store as partcount
Ignore other fields (start, count.total, count.bad)

Extended JSON Path Syntax

For complex JSON structures with nested objects and arrays, use extended JSON path notation.

Syntax Overview:

Basic Path: machine.system.state (dot notation)
Array Search: machines[id=102].location (find object in array)
Array Index: machines.0.name (access first element)

Example 1: Basic Nested Path

JSON:

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

JSON Path: a.b.c

Result: "test"

Example 2: Array Search

JSON:

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

JSON Path: g.h[i=j].k

Result: "test-search-array"

Explanation: [i=j] searches array g.h for an element where property i equals "j", then extracts k from that element.

Example 3: Root Array Search

JSON:

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

JSON Path: [l=m].n[o=p].q

Result: "test-search-array-root"

Explanation: Searches root array for object where l equals "m", then searches nested array n for object where o equals "p", then extracts q.

Example 4: Array Index

JSON:

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

JSON Path: 0.r.s

Result: "test-index-array"

Explanation: Access first element (0) of root array, then navigate to r.s.

Using Data in MachineMetrics

Once data is collected from MQTT topics, you can:

1. Store in Variables

Use collected data in adapter script variables:

variables:
  execution:
    - state: is-running
    - ACTIVE: true
    - READY: false

2. Export as Data Items

Export selected data to MachineMetrics dashboards:

data-items:
  - execution
  - press-speed
  - program-name

3. Apply Transformations

Use adapter scripts to transform data:

variables:
  speed_metric:
    - speed_mph: press-speed
    - multiply: 1.60934  # Convert MPH to KPH
    
data-items:
  - speed_metric

For more details on adapter scripts, see: Transform Adapter Scripts Guide

Lincoln Electric Machines

Lincoln Electric welding machines publish MQTT messages to an MQTT broker. MachineMetrics connects to this broker and subscribes to the welder's topics to collect real-time weld telemetry — including current, voltage, wire speed, motor current, weld records, and summary metrics.

OEM Responsibility

Setup and configuration of Lincoln Electric MQTT Publisher settings — including licensing, enabling MQTT output, and determining topic structure — are OEM-controlled. This section covers only how to connect an already-configured welder to MachineMetrics.

note

MachineMetrics is a read-only MQTT subscriber. It does not send any commands or configuration changes back to the welder.

How It Works

[Lincoln Welder]
       → publishes →
[MQTT Broker]
       → subscribed by →
[MachineMetrics Edge Adapter]
       → MachineMetrics Cloud

MachineMetrics supports two broker configurations:

A MachineMetrics-hosted Mosquitto broker running on the MachineMetrics Edge device
A customer-hosted MQTT broker

Both the welder and the MachineMetrics Edge must be able to reach the same broker on TCP port 1883.

Feature Availability

Category	Details
OEM Manufacturer	Lincoln Electric
Supported Models	Welders that support the Lincoln Electric MQTT Publisher
Integration Method	MQTT (Lincoln Electric)
MachineMetrics Module	Edge → Data Collection
Access Level	Manager / Executive / IT Admin

Prerequisites

Lincoln Electric welder with MQTT Publisher enabled
Unique MQTT Client ID for each welder
MQTT broker reachable from both the welder and the Edge
Topic schema provided by the customer or integrator
Firewall rules allowing TCP port 1883
If using an Edge-hosted broker: Docker access and stable Edge IP address

warning

Using duplicate MQTT Client IDs across multiple welders will cause connection drops, message collisions, and lost data. Every welder must have a unique Client ID.

Configure on the Machine (OEM Responsibility)

All welder-side setup is performed in Lincoln Electric's software:

Enable the MQTT Publisher
Configure the broker address:
```
mqtt://<broker_ip>:1883
```
Assign a unique MQTT Client ID
Define the topic structure — common patterns include:
- lincoln/<serial>/#
- lincoln/<cell>/<welder>/#
Restart the welder's data service if required

Configure the MQTT Broker

Provide the following to MachineMetrics:

Broker hostname or IP
Port (default: 1883)
Username and password (if required)
Required topic prefixes
ACL requirements

These values are used in the MachineMetrics adapter configuration.

Configure in MachineMetrics

Add a new MQTT data source in MachineMetrics Edge.

For a MachineMetrics-hosted broker (Edge-hosted Mosquitto):

mqtt://customservices_mosquitto_1

For a customer-hosted broker:

mqtt://<broker_ip>:1883

Subscribe to Lincoln Electric topics:

topics:
  - "lincoln/#"

note

No custom adapter scripting is required for Lincoln Electric. MachineMetrics automatically maps all MQTT payload fields into the Lincoln Electric data model.

During discovery, the adapter will list serial numbers found in incoming messages. Assign each serial number to the correct machine in MachineMetrics.

Verification & Testing

To test the broker directly:

mosquitto_sub -h <broker_ip> -t "lincoln/#" -v

On the MachineMetrics Edge device:

The MQTT adapter should show Connected
Logs should show continuous incoming MQTT messages
No repeated disconnections should occur

In MachineMetrics Cloud:

Live weld telemetry should update in real time
Weld values should change during machine activity
Summary metrics should appear for completed welds

warning

If timestamps do not update, verify the welder is publishing to the expected topics and that the broker address is correct.

Troubleshooting

Symptom	Likely Cause	Resolution
No data in MachineMetrics	Incorrect broker IP or welder not publishing	Validate welder publishing configuration
Broker unreachable	Firewall or VLAN blocking traffic	Allow TCP port 1883
Intermittent data	Duplicate MQTT Client IDs	Ensure all Client IDs are unique
Missing serial numbers	Welder not publishing identifying fields	Enable welder serial-publishing topics

warning

Do not use Wi-Fi for production welding telemetry. Wireless instability will cause inconsistent weld data.

Best Practices

Use the Edge-hosted Mosquitto broker whenever possible
Maintain unique Client IDs for every welder
Document the topic schema for support and scaling
Use secure passwords and ACLs on the broker
Validate network routing before commissioning
Keep MachineMetrics Edge firmware updated

Contact support@machinemetrics.com for assistance with Lincoln Electric MQTT configuration.

Examples

Tip: Use Max — MachineMetrics’ AI assistant — to help generate or refine an adapter script for your MQTT topics and payloads. The examples below are starting points.

Example 1: 3D Printer with Event-Based Counting

Scenario: 3D printer publishes build start/end events and status via MQTT

Configuration:

version: 2

topics:
  # Subscribe to build start events for any printer
  vf1.0/Printers/P12/PrinterPLC/EVENT/EventBuildStart:
    json:
      start-lot: lot_id
      start-time: timestamp
      start-layer: layer
      
  # Subscribe to build end events for any printer  
  vf1.0/Printers/P12/PrinterPLC/EVENT/EventBuildEnd:
    json:
      end-lot: lot_id
      end-time: timestamp
      end-layer: layer
      
  vf1.0/Printers/P12/PrinterPLC/EVENT/Status:
    json:
      status: active
      part: prg
      count: cnt  
  
variables:
  # Count build start events
  start-count:
    - source: start-time
    - value-change
    - count
    
  # Count build end events
  end-count:
    - source: end-time
    - value-change
    - count
    
  # Execution: ACTIVE when build in progress (starts > ends)
  execution:
    - source: start-count > end-count
    - state:
      - ACTIVE: this
      - READY: true
      
  # Part count = completed builds
  part-count:
    - source: end-count

data-items:
  - execution
  - part-count
  - start-lot
  - end-lot
  - start-layer
  - end-layer

Example 2: Palletizer with Comprehensive Metrics

Scenario: Palletizer publishes production counts, metrics, and state information with authentication

Configuration:

version: 2
username: USER1
password: PWD2026!
scan-interval: 0.5

topics:
  # --- Production Counts ---
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/count/outfeed: outfeed
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/count/infeed: infeed
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/rate/instant: rate_instant
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/input/infeedtooutfeed: infeed_to_outfeed
  
  # --- Metrics ---
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/oee: oee
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/availability: availability
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/performance: performance
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/quality: quality
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/rateactual: rate_actual
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/ratestandard: rate_standard
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/countinfeed: infeed_count
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/countoutfeed: outfeed_count
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/timedownunplanned: time_downtime_unplanned
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/timedownplanned: time_downtime_planned
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/timeidle: time_idle
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/timerunning: time_running
  Enterprise B/Site1/palletizing/palletizer01/pallet01/metric/input/countdefect: defect_count

  # --- State ---
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/state/code: state_code
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/state/name: state_name
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/state/type: state_type
  Enterprise B/Site1/palletizing/palletizer01/pallet01/processdata/state/duration: state_duration
  
  # --- Asset Identifier ---
  Enterprise B/Site1/palletizing/palletizer01/pallet01/node/assetidentifier/assetid: asset_id
  Enterprise B/Site1/palletizing/palletizer01/pallet01/node/assetidentifier/displayname: display_name
  Enterprise B/Site1/palletizing/palletizer01/pallet01/node/assetidentifier/assettypename: asset_type_name
  Enterprise B/Site1/palletizing/palletizer01/pallet01/node/assetidentifier/sortorder: sort_order
  Enterprise B/Site1/palletizing/palletizer01/pallet01/node/assetidentifier/assetname: asset_name
  Enterprise B/Site1/palletizing/palletizer01/pallet01/node/assetidentifier/parentassetid: parent_asset_id

variables:
  execution:
    - source: state_type
    - state:
      - ACTIVE: this == 'Running'
      - READY: true

  running:
    - source: state_type == 'Running'

data-items:
  - execution
  - running
  - outfeed
  - infeed
  - rate_instant
  - infeed_to_outfeed
  - state_code
  - state_name
  - state_type
  - state_duration
  - asset_id
  - display_name
  - asset_type_name
  - sort_order
  - asset_name
  - parent_asset_id
  - oee
  - availability
  - performance
  - quality
  - rate_actual
  - rate_standard
  - infeed_count
  - outfeed_count
  - time_downtime_unplanned
  - time_downtime_planned
  - time_idle
  - time_running
  - defect_count

Troubleshooting

Connection Issues

Problem: Cannot Connect to MQTT Broker

Possible causes:

Incorrect IP address or port
Broker not running
Network connectivity issue
Firewall blocking MQTT traffic
Authentication failure

Solutions:

Verify broker IP address and port (default 1883)
Test connectivity with ping to broker IP
Verify broker is running (check with MQTT client tool)
Check firewall rules allow port 1883
Verify username/password if authentication is enabled

Test connection with Mosquitto client:

mosquitto_sub -h 192.168.1.100 -t test/topic -u username -P password

Problem: Connected But No Data

Possible causes:

Machine not publishing to topics
Subscribed to wrong topics
Topic names misspelled

Solutions:

Verify machine is publishing (check machine configuration)
Use MQTT client to verify topics:
```
mosquitto_sub -h 192.168.1.100 -t # -v
```
(subscribes to all topics)
Check topic names for typos in configuration
Verify topic structure matches machine's published topics

Data Extraction Issues

Problem: JSON Extraction Not Working

Possible causes:

Incorrect JSON path
JSON structure different than expected
Data not actually JSON (plain text)

Solutions:

Subscribe to topic with MQTT client to see actual message format
Verify JSON path syntax (test with online JSON path tester)
Check for nested arrays or objects
Ensure json: keyword is used in configuration
Review adapter logs for parsing errors

Problem: Wrong Values Extracted

Possible causes:

JSON path points to wrong field
Data type conversion issue
Missing array index or search criteria

Solutions:

Review JSON message structure carefully
Test JSON path with sample message
Verify array indexes or search criteria
Check for multiple fields with similar names

Authentication Issues

Problem: Authentication Failed

Possible causes:

Incorrect username or password
Broker not configured for authentication
Special characters in password not escaped

Solutions:

Verify username and password are correct
Check broker authentication configuration
Escape special characters in YAML (use quotes)
Test credentials with MQTT client tool
Check broker logs for authentication errors

Performance Issues

Problem: High Latency or Missed Messages

Possible causes:

Network congestion
High message frequency
Broker overloaded
Large JSON payloads

Solutions:

Monitor network bandwidth and latency
Reduce message frequency if possible
Check broker resource usage (CPU, memory)
Optimize JSON payload size
Consider QoS (Quality of Service) settings

Additional Resources

MachineMetrics Resources:

Transform Adapter Scripts Guide - Advanced data transformation
Machine Settings Guide - Configure data mapping
Connectivity Overview - Compare connectivity methods

MQTT Resources:

MQTT.org: https://mqtt.org/
Mosquitto Broker: https://mosquitto.org/
HiveMQ: https://www.hivemq.com/
MQTT Explorer (GUI tool): http://mqtt-explorer.com/

Related Guides:

Getting Help

MachineMetrics Support:

Email: support@machinemetrics.com
Phone: 844-822-0664

Before Contacting Support:

Note machine make, model, and MQTT capability
Document MQTT broker IP address and port
Test MQTT connectivity with client tool (Mosquitto)
Capture sample MQTT messages from topics
Note topic names and data format (raw or JSON)
Review adapter logs in MachineMetrics

Information to Provide:

Machine make and model
MQTT broker details (embedded or external, IP, port)
List of subscribed topics
Sample MQTT messages (raw data or JSON)
Adapter configuration (YAML)
Description of issue and troubleshooting steps taken
Screenshots of MQTT client tool showing messages

For JSON Extraction Issues:

Provide complete JSON message example
Note the field you're trying to extract
Include JSON path you're using
Describe expected vs actual results

Overview​

What is MQTT​

Two Setup Scenarios:​

When to Use MQTT​

Prerequisites​

MQTT Broker vs Client Setup​

Check Your Machine's MQTT Support​

Setting Up External MQTT Broker (If Needed)​

Adding Machine in MachineMetrics​

Basic Configuration​

Authentication Setup​

Subscribing to Topics​

Data Extraction Methods​

Reading Raw Data​

Extracting JSON Data​

Extended JSON Path Syntax​

Example 1: Basic Nested Path​

Example 2: Array Search​

Example 3: Root Array Search​

Example 4: Array Index​

Using Data in MachineMetrics​

Lincoln Electric Machines​

How It Works​

Feature Availability​

Prerequisites​

Configure on the Machine (OEM Responsibility)​

Configure the MQTT Broker​

Configure in MachineMetrics​

Verification & Testing​

Troubleshooting​

Best Practices​

Examples​

Example 1: 3D Printer with Event-Based Counting​

Example 2: Palletizer with Comprehensive Metrics​

Troubleshooting​

Connection Issues​

Data Extraction Issues​

Authentication Issues​

Performance Issues​

Additional Resources​

Getting Help​

Overview

What is MQTT

Two Setup Scenarios:

When to Use MQTT

Prerequisites

MQTT Broker vs Client Setup

Check Your Machine's MQTT Support

Setting Up External MQTT Broker (If Needed)

Adding Machine in MachineMetrics

Basic Configuration

Authentication Setup

Subscribing to Topics

Data Extraction Methods

Reading Raw Data

Extracting JSON Data

Extended JSON Path Syntax

Example 1: Basic Nested Path

Example 2: Array Search

Example 3: Root Array Search

Example 4: Array Index

Using Data in MachineMetrics

Lincoln Electric Machines

How It Works

Feature Availability

Prerequisites

Configure on the Machine (OEM Responsibility)

Configure the MQTT Broker

Configure in MachineMetrics

Verification & Testing

Troubleshooting

Best Practices

Examples

Example 1: 3D Printer with Event-Based Counting

Example 2: Palletizer with Comprehensive Metrics

Troubleshooting

Connection Issues

Data Extraction Issues

Authentication Issues

Performance Issues

Additional Resources

Getting Help