MQTT Connectivity

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

Special Note: If connecting a Lincoln Electric welding machine, see the dedicated Lincoln Electric section below for specific MQTT topic structures and data formats that require specialized configuration.

Examples

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
Support Portal: https://support.machinemetrics.com

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​

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

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