Set up an MTConnect Agent in three or so steps

In the past few months, I’ve written about MTConnect on several occasions. I’ve even posted a walkthrough for installing the MTConnect agent on a Debian system.

Lately I’ve seen a few visitors searching for information on MTConnect agent setup. I don’t really have a walkthrough for completely setting up the MTConnect agent, but I thought I’d post a very brief overview.

Step 0: Get your tool ready for MTConnect

This step takes the most work, because it’s the least standardized part of the process. Typically, the MTConnect Agent collects data from a component called an Adapter. An adapter might be hardware, like an adapter box. Or for newer controls, it might be a low-cost software option.

Some adapters work with proprietary APIs, such as FOCAS. Some collect CNC data through a PLC via Modbus. Some translate from another existing data provider, such as OPC.

A few toolbuilders have been very supportive of the MTConnect standard, and provide fully-featured adapters. For some other CNCs, the community has stepped up to fill this need.

Whatever the case, you’ll need to obtain an MTConnect adapter for your CNCs. Check with your distributor or toolbuilder first.

Step 1: Get the Agent source code

The MTConnect Institute provides C++ source code for the Agent on GitHub The GitHub repository contains a very complete explanation of how to build the agent, as well as how to configure it. Since the README file is updated whenever a significant change occurs to the code, you should consult it for the latest information on building and configuration options.

Near the top of the page, on the toolbar, you have several options. Click on the “ZIP” button to download the source code as a ZIP file.

Step 2: Build the Agent

To build the Agent, you’ll need CMake, which is downloadable here.

If you’re on a Windows machine, you’ll also need a C++ compiler installed on your system, such as the one that comes with Visual Studio. (You’ll need this on a Linux box as well, but you’re much more likely to already have one on your system.)

Extract the zipped source code and run cmake:

> cmake .

Then build the project. If you’re on Linux, just run “make” immediately afterward. On my Windows development machine, cmake generated an .sln file (and various project files) for Visual Studio, which I opened and built. The output was the executable MTConnect Agent.

It would be convenient if pre-compiled binaries were available for Windows. The README on GitHub suggests that they’re provided in a /bin directory, but that’s not present in the repository (and is probably excluded automatically by Git).

Step 3: Configure the MTConnect Agent

Now you have the MTConnect Agent executable, but you’ll need to configure it before you run it. There are two configuration files that you’ll probably need to modify.

agent.cfg

The MTConnect Agent needs to know some basic information about how it should work. If you’re coming from the .NET world, you might expect it to look for an App.config file containing XML configuration data. Or if you have a Linux background, you might expect it to look for an agent.conf file containing sections and key-value pairs.

In what seems to be a fair compromise, the agent looks for neither of these. Instead, it looks for a file named agent.cfg, which is in something called “Boost C++ file format”. Whatever that is, it’s pretty straightforward. Let’s look at an agent.cfg that’s minimal but still instructive.

Devices = VMC-3Axis.xml

Adapters
{
  VMC-3Axis
  {
    Host = 192.168.10.22
    Port = 7878 # *Default* value...
  }
}

This example is taken straight from the README.

The “Devices” line tells the agent to look for a file named “VMC-3Axis.xml” for device configuration. I’ll cover that momentarily.

The Adapters section is everything contained in the curly braces following “Adapters”. In this example, there is a single adapter definition, named “VMC-3Axis”. That name is just for your convenience: the adapter could be named “Adapter1”, “MyMachineAdapter”, or “Bob” with no change in meaning.

The definition for “VMC-3Axis” is everything contained in the curly braces following it. The specified Host is 192.168.10.22, and the specified Port is 7878 (the hash “#” is a comment). This tells the MTConnect Agent where the Adapter should be located.

You can specify zero or more adapters within the “Adapters” section. If you specify none, the MTConnect Agent will attempt to connect to localhost on port 7878. See the README for the MTConnect Agent for a full list of supported configuration items for an adapter.

The MTConnect Agent README also lists additional configuration options for the Agent itself. For example, if you want the Agent to run on on a port other than the default port 5000, you can specify that with a Port line.

Devices.xml

Next, the MTConnect Agent needs to know about the data it should serve. By default, it will look for a Devices.xml file, whose format is exactly the format of an MTConnectDevices document that it would serve in response to a probe request.

Here’s another example taken from the /sample folder of the MTConnect Agent code. (I’ve stripped out a few bits for brevity.)

<?xml version="1.0" encoding="UTF-8"?>
<MTConnectDevices xmlns:m="urn:mtconnect.org:MTConnectDevices:1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mtconnect.org:MTConnectDevices:1.1">
  <Header creationTime="2009-03-22T01:50:29+00:00" sender="localhost" instanceId="1237628993" bufferSize="100000" version="1.1"/>
  <Devices>
    <Device uuid="000" name="LinuxCNC" sampleInterval="10.0" id="d">
      <Description manufacturer="NIST" serialNumber=""/>
      <Components>
        <Controller name="Controller" id="cont">
	  <Components>
	    <Path name="path" id="path">
              <DataItems>
		<DataItem type="BLOCK" category="EVENT" id="p1" name="block"/>
		<DataItem type="CONTROLLER_MODE" category="EVENT" id="p2" name="mode"/>
		<DataItem type="LINE" category="EVENT" id="p3" name="line"/>
		<DataItem type="PROGRAM" category="EVENT" id="p4" name="program"/>
              </DataItems>
	    </Path>
	  </Components>
        </Controller>
      </Components>
    </Device>
  </Devices>
</MTConnectDevices>

I won’t go into detail here about how to create the file, but the key point is to make sure that the data served up by your Adapter is hooked up to a DataItem tag somewhere. The Adapter will output data in a form that might look something like this:

2013-05-13T16:00:05.0000Z|mode|AUTOMATIC

The MTConnect Agent will interpret that as meaning that some item with a key of “mode” has a new value of “AUTOMATIC”, as of the given timestamp. The Agent will then try to map “mode” to one of the DataItem tags specified in Devices.xml, by matching it up with a DataItem whose Source, name, or id matches the key. In this case, it will find the following DataItem:

<DataItem type="CONTROLLER_MODE" category="EVENT" id="p2" name="mode"/>

Cross your fingers

And there you have it. Your MTConnect Agent is built. Your agent.cfg and Devices.xml configuration files are ready. Now just run the MTConnect Agent. If all is well, you should now be able to load http://localhost:5000/current/ (or run your chosen MTConnect client application) and see data from your machine tool, served by the MTConnect Agent. Good luck!

If anything that I said was unclear, glossed-over, incomplete, or just flat-out wrong with a capital-R, please let me know. 🙂

Advertisements