MTConnect Integration Guide

Use MaestroHub's MTConnect connector to collect real-time data from CNC machines, manufacturing equipment, and industrial devices that support the MTConnect standard. This guide explains how to configure connections, query device data, and integrate equipment monitoring into your pipelines.

Overview

The MTConnect connector provides:

• Read-only access to MTConnect agents for device discovery, current values, and historical data
• Four query types – Probe (device structure), Current (latest values), Sample (time-series), and Assets (tools, fixtures)
• XML and JSON support for flexible response handling
• Stateless HTTP-based connections that can be shared across replicas
• Built-in function testing with a dedicated test dialog for validating queries before use

What is MTConnect?

MTConnect is an open, royalty-free standard for exchanging data from manufacturing equipment. An MTConnect Agent collects data from machines via Adapters and serves it over HTTP. MaestroHub acts as a client, querying the agent for device information and process data. No authentication is required — the specification states "no logon or logoff sequence is required."

Connection Configuration

Creating an MTConnect Connection

Navigate to Connections → New Connection → MTConnect and configure the following settings. The form is organized into four tabs: Connection, Advanced, Functions, and Health.

1. Profile Information

Field	Default	Description
Profile Name	—	A descriptive name for this connection profile (required, max 100 characters). Must be unique across all connections.
Description	—	Optional description for this MTConnect connection

2. MTConnect Agent Settings

Field	Default	Description
Agent URL	—	Full URL of the MTConnect agent (required). Must start with http:// or https://.
Health Check Endpoint	/probe	Endpoint path used for connection testing and health checks
Response Format	xml	Preferred response format from the agent: XML (standard MTConnect) or JSON (if supported by agent)
Skip TLS Verification	false	Do not verify the server's TLS certificate. Enable only for self-signed certificates in non-production environments.

Agent URL Examples

• http://192.168.1.100:5000 — Direct IP address with custom port
• http://cnc-agent.factory.local:5000 — DNS hostname on factory network
• https://mtconnect.example.com — Secure endpoint with TLS

Security Note

MTConnect does not define an authentication mechanism — security relies on network segmentation. Deploy agents on isolated OT networks and control access at the firewall level. Some MTConnect 2.0 agents support optional TLS, but this is implementation-specific. Use the Skip TLS Verification toggle only for testing with self-signed certificates.

3. Advanced Settings

The Advanced tab contains request tuning options:

Field	Default	Description
Request Timeout (ms)	30000	Maximum time to wait for an agent response (1,000–300,000 ms)

4. Connection Labels

Field	Default	Description
Labels	—	Key-value pairs to categorize this connection (max 10 labels)

Example Labels

• environment: production — Deployment environment
• cell: machining-01 — Manufacturing cell
• equipment-type: cnc — Equipment category
• location: building-a — Physical location

Configuration Example

Below is an example of the JSON configuration stored for an MTConnect connection:

{
  "agentUrl": "http://192.168.1.100:5000",
  "responseFormat": "xml",
  "healthCheckEndpoint": "/probe",
  "timeout": 30000,
  "tlsSkipVerify": false
}

Function Builder

Creating MTConnect Functions

After the connection is saved:

1. Open the connection and navigate to the Functions tab
2. Click New Function to open the function type selection dialog
3. Choose the function type: Probe, Current, Sample, or Assets
4. Fill in the Basic tab (name, description, labels) and the Configuration tab (query parameters)
5. Use the Test button to validate the function before saving

Each function has two configuration tabs:

• Basic — Function name (required, max 100 characters, must be unique within the connection), optional description, and labels
• Configuration — Query-specific parameters that vary by function type

Probe Function (mtconnect.probe)

Purpose: Discover device structure and capabilities. Use this to understand what data items are available from a machine before querying values.

Configuration Fields

Field	Type	Required	Default	Description
Device Name	String	No	—	Filter by device name (e.g., Mill-001). Leave empty to retrieve all devices from the agent.

Response Structure

Returns device metadata including:

• Device identifiers (id, name, uuid)
• Component hierarchy (axes, controllers, systems)
• Available data items with types and units

Use Cases: Initial setup, discovering available tags, documenting machine capabilities

Example Configuration

{
  "functionType": "mtconnect.probe",
  "configVersion": "1.0.0",
  "device": "Mill-001"
}

Current Function (mtconnect.current)

Purpose: Get the latest value for each data item. Returns a snapshot of current machine state without historical context.

Configuration Fields

Field	Type	Required	Default	Description
XPath Filter	String	No	—	XPath expression to filter data items (e.g., //DataItem[@type="POSITION"])
At Sequence	Number	No	—	Retrieve data at a specific sequence number. Leave empty for the latest values. Must be ≥ 0.

Response Structure

Returns current values including:

• Data item values with timestamps
• Sequence numbers for change tracking
• Component and device context

Use Cases: Real-time dashboards, current state monitoring, snapshot collection

Example Configuration

{
  "functionType": "mtconnect.current",
  "configVersion": "1.0.0",
  "path": "//DataItem[@type=\"POSITION\"]"
}

Example with sequence number

{
  "functionType": "mtconnect.current",
  "configVersion": "1.0.0",
  "path": "//DataItem[@category=\"SAMPLE\"]",
  "at": 54321
}

Sample Function (mtconnect.sample)

Purpose: Retrieve historical time-series data. Use this for trend analysis, data logging, or catching up on missed values.

Configuration Fields

Field	Type	Required	Default	Description
XPath Filter	String	No	—	XPath expression to filter data items (e.g., //DataItem[@type="TEMPERATURE"])
From Sequence	Number	No	—	Starting sequence number for incremental collection. Leave empty for oldest available. Must be ≥ 0.
Sample Count	Number	No	100	Maximum number of samples to return (1–10,000)

Response Structure

Returns time-series data including:

• Ordered sequence of data item values
• Timestamps for each sample
• Sequence numbers for pagination

Use Cases: Historical analysis, data backfill, incremental data collection, trend monitoring

Incremental Collection

Store the last sequence number from each response. On the next request, use it as the From Sequence parameter to collect only new data without duplicates.

Example Configuration

{
  "functionType": "mtconnect.sample",
  "configVersion": "1.0.0",
  "path": "//DataItem[@type=\"TEMPERATURE\"]",
  "from": 12345,
  "count": 500
}

Assets Function (mtconnect.assets)

Purpose: Retrieve asset information such as cutting tools, fixtures, workpieces, and programs stored in the agent.

Configuration Fields

Field	Type	Required	Default	Description
Asset ID	String	No	—	Retrieve a specific asset by its unique ID (e.g., TOOL-001). When provided, type and count filters are ignored.
Asset Type	String	No	—	Filter by asset type (e.g., CuttingTool, Fixture). Only used when Asset ID is empty.
Asset Count	Number	No	100	Maximum number of assets to return (1–1,000). Only used when Asset ID is empty.

Response Structure

Returns asset details including:

• Asset identifiers and types
• Tool life and measurement data
• Custom asset properties

Use Cases: Tool management, fixture tracking, program versioning, asset inventory

Example — Retrieve a specific asset

{
  "functionType": "mtconnect.assets",
  "configVersion": "1.0.0",
  "assetId": "TOOL-001"
}

Example — List assets by type

{
  "functionType": "mtconnect.assets",
  "configVersion": "1.0.0",
  "assetType": "CuttingTool",
  "count": 50
}

Testing Functions

Every MTConnect function can be tested before saving using the built-in Test dialog:

1. Click the Test button in the function form
2. The dialog shows an Execution Overview with the current configuration
3. Override any parameter values in the Test Parameters section
4. Click Execute Test to run the function against the live agent
5. View the result in the integrated JSON viewer, including execution duration and timestamp

The test dialog supports two modes:

• Config-only Testing (create mode) — Tests the function configuration before saving
• Function with Overrides (edit mode) — Tests the saved function with current form modifications

Understanding MTConnect Data

Data Item Categories

MTConnect organizes data into three categories:

Category	Description	Examples
Samples	Continuously variable numeric values	Position, temperature, spindle speed, load
Events	Discrete state changes	Execution state, program name, operator mode
Conditions	Alarm and warning states	Faults, warnings, normal status

Common Data Item Types

Type	Category	Description
POSITION	Sample	Axis position in configured units
SPINDLE_SPEED	Sample	Spindle rotational speed (RPM)
LOAD	Sample	Component load percentage
TEMPERATURE	Sample	Temperature reading in configured units
EXECUTION	Event	Program execution state (ACTIVE, STOPPED, READY, etc.)
PROGRAM	Event	Currently loaded program name
AVAILABILITY	Event	Device availability (AVAILABLE, UNAVAILABLE)
CONTROLLER_MODE	Event	Controller operating mode (AUTOMATIC, MANUAL, etc.)
SYSTEM	Condition	System-level fault conditions

XPath Filtering

Use the XPath Filter field in Current and Sample functions to narrow results:

Pattern	Description
//DataItem[@type="POSITION"]	All position data items
//DataItem[@category="SAMPLE"]	All continuously variable data items
//Device[@name="Mill"]//*	All data from device named "Mill"
//Axes//*	All data from Axes components
//Controller//DataItem	All controller data items
//DataItem[@category="CONDITION"]	All condition/alarm data items

Pipeline Integration

Use MTConnect functions in the Pipeline Designer to build automated data collection workflows. Drag the MTConnect node onto the canvas, select your connection and function, and bind parameters to upstream outputs or constants.

Example Pipeline Patterns

1. Periodic Polling — Schedule a pipeline to run every minute, collect current values, and store in a database
2. Incremental Collection — Track sequence numbers, collect only new samples since the last run
3. Event-Driven — Trigger on an external event, probe device state, and route based on conditions
4. Multi-Machine Aggregation — Fan out to multiple MTConnect connections, merge results, and publish to a UNS topic

If you're designing larger orchestrations, the Connector Nodes page shows how MTConnect nodes fit alongside other industrial protocols.

Common Use Cases

Machine Monitoring Dashboard

Collect current values from multiple CNC machines and display real-time status on operator dashboards showing spindle speed, axis positions, and execution state.

OEE Data Collection

Use Sample functions to collect historical data for calculating Overall Equipment Effectiveness — availability, performance, and quality metrics over time.

Tool Life Tracking

Query Assets functions to monitor cutting tool usage and remaining life, triggering alerts when tools approach replacement thresholds.

Predictive Maintenance

Collect load, vibration, and temperature samples over time. Feed this data to analytics systems to detect anomalies before equipment failures occur.

Production Reporting

Combine execution state events with part count data to generate shift reports, tracking cycle times, downtime reasons, and production quantities.

Troubleshooting

Connection Issues

Symptom	Possible Cause	Solution
Connection timeout	Agent not reachable	Verify network connectivity and firewall rules. Check that the agent URL and port are correct.
Invalid URL error	Malformed agent URL	Ensure URL includes protocol (http:// or https://) and is a valid URL format.
TLS certificate error	Self-signed certificate	Enable Skip TLS Verification for testing only. Use proper certificates in production.
Health check fails	Wrong health check endpoint	Verify the Health Check Endpoint path (default /probe) matches your agent configuration.

Function Issues

Symptom	Possible Cause	Solution
Empty response	No matching devices	Remove the device name filter or verify the device name using a Probe function first.
Missing data items	XPath filter too restrictive	Simplify the XPath expression or use Probe to discover the available data item structure.
Stale data	Agent buffer overflow	Increase polling frequency or use smaller count values with incremental from sequence tracking.
Sequence number errors	Invalid sequence range	Use a Probe or Current function to discover the current sequence range before querying samples.
Asset not found	Incorrect asset ID	Use an Assets function without an Asset ID to list available assets and verify the correct ID.

Testing Functions

Use the Test button in the Function Builder to validate your configuration before using it in pipelines. The test dialog lets you override parameters for one-off queries and displays the full response with execution timing.