An example of how to build a driver using CM Connect IoT, for a very popular driver. All the source code of this driver is available here.
Overview
MTConnect is a very common standard in the world of CNC (Computer Numerical Control) machines. These are machines that have very long life cycles and typically have had very disparate interface support. Some are very capable, able to have full control and recipe management but most being quite limited.
MTConnect is an open standard that tries to mitigate this gap, by having an easy and standard way to make information available. It is vendor agnostic and is read only. It is part of the push of Industry 4.0 to surface machine information that was until now being ignored or discarded.
It uses an XML based format to provide machine information through HTTP. It allows for machines that were, until know, black boxes to easily start servicing information.
The MES is a common consumer of this type of machine data, for process control and material tracking. Therefore an MTConnect driver for Connect IoT makes a lot of sense.
The standard is maintained by the MTConnect Institute, and it’s widely adopted for CNC machines, robots, sensors, and other shop floor equipment.
Architecture
Let’s take some time understanding how the protocols works. MTConnect follows a client–agent–adapter model.
The Device will be the equipment that we want to gather information from.
The Adapter is a translation layer that is able to convert the machine data into MTConnect’s Observation format. This can be a piece of software or a hardware adapter running the needed software. It turns the machine data into very simple key/value text lines.
spindle_speed|1250
feedrate|300
The Agent is agnostic to the machine and transforms the key/values into standardized MTConnect XML format. It also is responsible for:
hosting an HTTP Rest server, that services the MTConnect endpoints
implementing caching
multiplexer mechanisms.
It acts as the data cache and historical snapshot point.
The Client will be the data consumer. It is the application that will be making requests to the Agent to extract device information. The MES is a Client, so our driver will be the creation of an MTConnect Client.
MTConnect Endpoints
In MTConnect the agent provides a set of endpoints.
/probe → device discovery
/current → latest values
/sample → historical time-series data
/assets → tooling or program assets
/asset → tooling or program asset
/probe – Device Discovery
Returns the device model — a hierarchical description of all components, data items, and capabilities of the connected machines.
Usage:
Called at the start of a client session to understand what the agent can provide.
Defines available DataItems (e.g., spindle speed, feed rate, temperature).
Output: XML or JSON that matches the Devices schema.
Example:
Request
GET http:///probe
Response
It exists to be called when configuration changes or at client initialization.
/current – Latest Values
Returns the most recent value for each DataItem.
Usage:
Quick “snapshot” of the machine’s current state.
Useful for dashboards that don’t need time-series history.
Output: XML or JSON with a timestamp for each DataItem.
Example:
Request
GET http:///current
Response
1250
Can be called every few seconds if you want near-real-time monitoring, or on demand.
/sample – Time-Series Data
Returns a sequence of observations for each DataItem between a from and to sequence number.
Usage:
Historical analysis.
Incremental polling: clients track the last sequence number and request new data since then.
Query Parameters:
from – starting sequence number.
count – max number of samples to return.
Output: XML or JSON with a timestamp for each DataItem.
Example:
Request
GET http:///sample?from=1523&count=100
Response
1250
1260
Can be called continuously in a loop for streaming-like updates.
/assets – Non-Time-Series Data
Provides static or semi-static information such as tool data, part programs, or maintenance logs.
Usage:
Retrieve tool offsets, part program code, or serialized asset metadata.
Often updated manually on the device or on events (e.g., tool change).
Query Parameters:
type – filter assets by type (e.g., CuttingTool).
count – limit results.
Output: XML or JSON with a timestamp for each DataItem.
Example:
Request
GET http:///assets?type=CuttingTool&count=10
Response
1/2 inch End Mill1/2 inch End Mill
/asset/ – Specific Asset
Retrieves a single asset by ID.
Usage:
Fetch the latest details about a specific tool or part.
Output: XML with a timestamp for each DataItem.
Example:
Request
GET http:///asset/T123
Response
1/2 inch End Mill
Building a Connect IoT Driver
One of the first decisions in any driver is what tools do you require to build driver support. For most drivers the starting point is made easy by the availability of SDKs or other tools made available by vendors or foundations.
For this particular example, we could simply use nodejs packages in order to perform http requests and implement all the xml parsers and validations. Fortunately, there are already a set of available and open source tools that do that work for us.
After some state of the art evaluation of the SDKs and tools for MTConnect we noticed that the .Net SDK MTConnect.NET had much more support and activity than other in .Net and in nodeJs. Also, very conveniently TrackHound provides a simple agent that we can use to start testing our driver against.
Even if Connect IoT is a nodeJs application, this is not an issue as it has full support for using .Net. Let’s see how.
Building a Connect IoT Driver
The full process is described in our developer portal. We will use the CM CLI to create our driver project.
Scaffolding a .Net Driver
The Connect IoT Driver is a component of a customization package for Connect IoT. In a CM customization project workspace, let’s create a new iot package.
Right away the scaffolding helps us a lot, by giving us a .Net solution where we can create our interface with MTConnect and a nodeJs workspace for the rest of the driver.
The scaffolding already provides a full on buildable and packable solution. In order to interact with the driver we can use the same commands that will be used by the pipeline to create a package with cmf build and cmf pack.
We can also decompose them into their subcommands.
With npm i to install the npm packages, npm run build to build the code, npm run test to test the code and npm run packagePacker to create a .tgz file with the driver bundled. Additionally, we also have support for the use of watchers that continuously build the code on changes, like npm run watchPackage, with this after every change to your source code, the code will automatically compile.
Defining our Settings for the UI
A good place to start the driver development is to start defining what are the settings the user will need to interact with.
For the driver, we will need:
address - ip or hostname of the MTConnect Agent
port - port of the Agent
device - we can hook our whole implementation to a particular device and then have this as a wrapper for all requests
The Device is very helpful as it can help us tie in with MES Resources, or MES durable materials, etc. If the MTConnect agent is servicing a lot of resources a filter by device may make it easier to interact with the data. Our client will only connect to one MTConnect Adapter.
In order for these settings to be available in the UI, we will need them to be part of our driver package.json.
"parameters": [
{
"name": "netCoreSdkVersion",
"label": ".Net Core SDK Version",
"description": "Set the .net core SDK version to use, when multiple are installed in the system where the driver is running. Leave empty to ignore this setting.",
"type": "string",
"defaultValue": ""
},
{
"name": "address",
"label": "MTConnect Agent Address",
"description": "Ip or Hostname of the MTConnect Agent",
"type": "string",
"defaultValue": ""
},
{
"name": "port",
"label": "MTConnect Agent port",
"description": "Port of the MTConnect Agent (leave as -1 for it to not be added)",
"type": "integer",
"defaultValue": -1
},
{
"name": "device",
"label": "MTConnect Device",
"description": "When specifying a device, all MTConnect interactions will filter by device.",
"type": "string",
"defaultValue": ""
}
],
From analyzing the Protocol, we already know that we have a predefined set of possible endpoints, we can map those as available command types.
"command": [
{
"name": "mtConnectCommandType",
"label": "Command Type",
"description": "Types of MTConnect commands that we are able to use.",
"type": "enum",
"values": [
"Probe",
"Current",
"Sample",
"Assets",
"Asset"
],
"defaultValue": "Probe"
}
],
The MTConnect.NET library that we are using on start, already emits information about the probe data, current data and starts a sampling process. We will see this in detail later, but for now we can create the metadata for our events.
"event": [
{
"name": "mtConnectEventType",
"label": "Event Type",
"description": "Types of MTConnect events that we are able to use.",
"type": "enum",
"values": [
"Probe",
"Current",
"Sample",
"Assets"
],
"defaultValue": "Probe"
}
],
Lastly, the MTConnect responses have two big fields, one which has Header information and another that has Device information, but they also have a lot of other fields inside the Device and the Header. So, let’s add a notion of expression to our event properties. With expressions our users can create their own JSONata expression, to retrieve the information from the JSON, that they wish. In order to achieve this parsing, we will later on use JSONata, for now, bear in mind this concept of expressions.
Info: The driver should try as much as possible to simplify it’s own usage and abstract complexity. This will make the workflows simpler and create cleaner implementations.
"property": [
{
"name": "expression",
"label": "Expression",
"description": "JSONata Expression to extract property from the JSON structure",
"type": "string",
"defaultValue": ""
}
]
Important: The driver in order to use .Net, requires the binaries for EdgeJs and EdgeJsBootstrap. Replace the folder name with the your edge-js version and copy the binaries there. The process of generating the binaries is described here.
Right now we can already create a package with this skeleton and uploaded it to the MES UI.
In the UI we are able to create an Automation Protocol with all our communication settings.
Info: Note that this is a development flow, for a productive flow, the cmf pack will create an installable package that will deploy the MTConnect driver..
Defining our Settings for the Driver
The package.json will describe the visualization settings for the UI, we can now define them for our driver.
In the communicationSettings.ts we can now declare our settings.
export interface MTConnectCommunicationSettings {
// Add driver specific settings here
/** Set the .net core SDK version to use, when multiple are installed in the system where the driver is running. Leave empty to ignore this setting. */
netCoreSdkVersion: string;
// MTConnect Address
address: string;
// MTConnect Address Port
port: number;
// MTConnect Device
device: string;
// Common/driver WS settings
heartbeatInterval: number;
setupTimeout: number;
intervalBeforeReconnect: number;
connectingTimeout: number;
};
/** Default Communication Settings */
export const mTConnectDefaultCommunicationSettings: MTConnectCommunicationSettings = {
// Add driver specific default settings here
/** Set the .net core SDK version to use, when multiple are installed in the system where the driver is running. Leave empty to ignore this setting. */
netCoreSdkVersion: "",
// Default MTConnect Address
address: "localhost",
// Default MTConnect Address Port
port: 5000,
// Default MTConnect Device
device: "",
// Common/driver WS settings
heartbeatInterval: 30000,
setupTimeout: 10000,
intervalBeforeReconnect: 5000,
connectingTimeout: 30000,
};
When the setCommunicationConfiguration is invoked in the lifecycle of the driver it will reconcile what was defined in the task Equipment Configuration, the package.json and the communication settings.
/**
* Notification regarding the communication parameters being available.
* Validate the integrity of the values
* Note: Called by the driverBase
* @param communication Communication settings object
*/
public async setCommunicationConfiguration(communication: any): Promise {
this._communicationSettings = Object.assign({}, mTConnectDefaultCommunicationSettings, communication);
// eslint-disable-next-line
const pJson = require("../package.json");
validateCommunicationParameters(pJson, this._communicationSettings);
// Prepare the extended data
validateProperties(pJson, this.configuration.properties);
validateEvents(pJson, this.configuration.events);
validateEventProperties(pJson, this.configuration.events);
validateCommands(pJson, this.configuration.commands);
validateCommandParameters(pJson, this.configuration.commands);
// Initialize assembly
this._mTConnectHandler.setPackageJson(pJson);
this._mTConnectHandler.setConfiguration(this.configuration, this._communicationSettings);
}
MTConnect .Net Logic
In the driver dotnet project, we can now import our dependency to MTConnect.NET-HTTP, to communicate with the MTConnect Agent and to MTConnect.NET-XML to parse the messages.
Costura.Fody
In the visual studio project our scaffolding creates there’s a file called FodyWeavers.xml, Costura.Fody allows us to merge all our dependencies into a single .dll file. This is not mandatory, but it allows us to simplify and better manage our bundles. There are some downsides, particularly if the there’s some of these dlls that is trying to load by reflection, example here was due to this issue.
Communication Settings
In the dotnet layer we will also need to have a match to the communication settings. The template generates the CommunicationSettings class at /DriverObjects/CommunicationSettings.cs.
We will add the settings:
/// IP address of the MTConnect Agent
public string Address { get; set; } = "";
/// Port of the MTConnect Agent
public int Port { get; set; } = 5000;
/// Device
public string Device { get; set; } = null;
And the loaders from the settings received from the nodejs layer: