Install the MTConnect Agent In Two Easy-ish Steps

A step-by-step guide to installing and configuring the MTConnect Agent, and an update to my earlier article, “Set up an MTConnect Agent in three or so steps“.

Prerequisites

Make sure your machine tools are MTConnect-ready

In the ten or so years since MTConnect emerged, this step has become much easier, as most machine-tool manufacturers support the standard in some way.

This may require additional hardware, e.g. for older machine tools where it may be necessary to integrate with a PLC or some type of I/O block. Or it may be a simple software option, such as through Fanuc FOCAS, Okuma THINC, or by adapting from another existing data provider, such as OPC.

The (very useful) MTConnect User’s Portal hosts a page listing supported functionality for several manufacturers, to give you an idea of what data you might extract from your machine tool.

Whatever the case, your local distributor or tool manufacturer can tell you what options are available to integrate your machine tool with an MTConnect ecosystem.

Choose your host platform

Where are you installing the MTConnect Agent?

A Linux server? That might mean anything from an Amazon EC2 cloud server, to a Raspberry Pi sitting on Jim’s desk. (Hi, Jim.)

In this case, you’ll need to be comfortable with the command-line. You don’t need to be an expert, but you will need to install prerequisite packages (through aptitude, yum, rpm, or whichever tool your distribution uses), edit configuration files, and run from the shell prompt.

A Windows machine? Again, that might be anything from a Windows Server 2019 box, to Jim’s old WinXP laptop. (Hi again, Jim.) Pre-built binaries are available for Windows, which means you won’t need to build it yourself.

Oh, and speaking of Jim’s old WinXP laptop…

Consider your security requirements

To be at all useful, the MTConnect Agent needs to be able to talk to your machine tools (or at least the adapters that are themselves connected to your machine tools) over the network.

I’ve seen machine shops whose network consisted of a single off-the-shelf wifi router. I’ve also seen machine shops whose network was a highly layered and isolated system managed by a full-time IT staff.

There is no way to generalize about this. But if you are the one-man IT department for your company, keep in mind that the data traveling from an MTConnect Adapter to an MTConnect Agent (SHDR protocol) and the data served by the MTConnect Agent (HTTP protocol) are sent as unencrypted cleartext.

Step 1 – Install the MTConnect Agent

On Debian Linux

Install the prerequisite packages. Elevate privileges and run:

apt install libxml2 libxml2-dev cmake git build-essential libcppunit-dev

Then pull the MTConnect Agent source code from GitHub:

git clone https://github.com/mtconnect/cppagent.git

Build the agent. (If you’re on a low-powered system like a Raspberry Pi, this will take a long time.)

cd cppagent

cmake .

make

You should then be able to run the agent, and see it listening on port 5000.

cd agent

./agent daemonize

netstat -anp –tcp

If you need further proof, try to fetch the device list and current state from the running agent:

wget localhost:5000

wget localhost:5000/current

You should now have two files in your working directory: index.html contains the device list, and current contains the current status.

On Windows

In a browser, navigate to the MTConnect Agent download page and download the current release.

Extract the ZIP file to wherever you want to install the agent. (For example, into “C:\Program Files\MTConnect Agent”.)

Then run a CMD window as administrator. Change directory to the bin/ path, and run the agent’s “install” routine, then its “run” routine.

cd “C:\Program Files\MTConnect Agent\bin\”

.\agent.exe install

.\agent.exe run

In your browser, you should be able to access the agent on port 5000:

Step 2 – Configure the MTConnect Agent

The “agent.cfg” file contains all configuration for the agent. Edit the file using the text editor of your choice. (I personally like Notepad++ on Windows, and nano on Linux.) The configuration file is in something called Boost C++ file format, and should look reasonably familiar if you’ve used JSON or YAML.

The readme contains a complete description of all configuration options, but let’s break down the default configuration so you can see what might need to change:

Devices = ../simulator/VMC-3Axis.xml

This tells the agent where to look for the Devices file, which is an XML file containing a complete description of the data the agent will serve. You will need to create a Devices XML file that includes all of your devices.

This might sound complicated, but your machine tool’s MTConnect adapter should also come with a sample device description that you can copy and paste.

One important thing to remember is that all of the “id” attributes must be unique throughout the entire file. So if you have two machine tools that each define an axes component as “<Axes id=”ax” name=”Axes”>”, then you should change the IDs to “ax1” and “ax2”.

AllowPut = true
ReconnectInterval = 1000
BufferSize = 17
SchemaVersion = 1.4

These lines tell the agent to allow HTTP PUT requests (an alternate method of updating data), to attempt to reconnect to the adapters every 1000 ms (or every one second), to maintain the last 17 data item changes in its buffer, and that it is running schema version 1.4.

You’ll probably want to bump up the buffer size.

Adapters { 

   VMC-3Axis { 

      Host = ::1

      Port = 7878

   } 

}

The “Adapters” section tells the agent about all of the adapters it should connect to.

In this case, it connects to one adapter, named “VMC-3Axis”. The Host parameter tells it the hostname of the adapter: “::1” is IPv6 shorthand for “localhost”, but you can also give it an IPv4 address or a hostname. Port 7878 is the default port for an MTConnect adapter.

You will need to add an entry for each of the adapters that the MTConnect Agent should connect to.

Files {

    schemas {

        Path = ../schemas

        Location = /schemas/

    }

    styles {

        Path = ../styles

        Location = /styles/

    }

    Favicon {

        Path = ../styles/favicon.ico

        Location = /favicon.ico

    }

}

The “Files” section tells the agent about additional static files that it should serve. In this case, it also serves schemas and styles for the agent, and a favicon to display in the browser’s location bar.

If you want to serve a web-based MTConnect viewer, this is a good place to specify it.

StreamsStyle {

  Location = /styles/Streams.xsl

}

This section tells the agent that there is an XSL (a document that can style an XML file) to use when displaying Streams. You can also specify a stylesheet for Devices, Assets, and Error responses.

# Logger Configuration
logger_config
 {
     logging_level = debug
     output = cout
 }

The agent will write logging messages to its default output. This tells the agent to log all messages at a level of “debug” or higher. The levels are “trace”, “debug”, “info”, “warn”, “error”, and “fatal”.

When going into production, you may wish to raise this up to “warn” so that you don’t fill up your log with debugging information.

You’ll also want to change the output, because “cout” means output to the console window. You can write to a file by specifying:

output = file log.txt

Incidentally, that ‘#’ symbol in front of “Logger Configuration” is a comment marker. Anything on a line after the “#” symbol will be ignored, so this is a good way to make notes about what a section does, or to disable a setting without deleting it.

And that’s it

Well… almost. Now that you’ve changed the configuration file, save it, and then close and restart the MTConnect Agent.

Now the agent should be running using your new settings. Verify that it’s running, that it loaded your new Devices file, and that it’s seeing data from the MTConnect adapters, and you’re golden.

But if you do run into problems, remember that there are plenty of resources for troubleshooting. If you’re not sure where to start, try the MTConnect User Forum to ask questions of a community knowledgeable about all things MTConnect.

[EDIT: as of 2020, the MTConnect User Forum is no longer active. Try checking StackOverflow for MTConnect-related questions and answers. Or if you message me your question, I’ll try to answer it or direct you to an appropriate resource.]