From MTConnect® User's Portal
Revision as of 13:27, 26 July 2013 by Tjones25 (Talk | contribs)

Jump to: navigation, search

This is a discussion of the concepts behind MTConnect's use of the HTTP protocol and the REST philosophy it has adopted. It will also discuss some best practices for implementing a client application to take advantage of Fault Tolerant capabilities built into the protocol as well as the ability to never miss a single event. We will also discuss how to use filtering to get just what you want and how best to create an application that uses multiple data streams from the same source depending on the data requirements.


MTConnect and REST

The MTConnect standard does not define its own protocol, but leverages the industry standard HTTP protocol and adds some RESTful interfaces on top of it. REST stands for REpresentational State Transfer. The term was first coined by Fielding in Chapter 5 of his thesis. The ideas of REST revolve around state management and who is responsible for managing connections and the data for that connection like the last message consumed and what information they are interested in. At the time of the paper, there was a lot of debate about the best way to architect web applications and manage client session state, which was a major limitation on server scalability and posed problems with replication and recovery.

The idea is that each request contains all the information necessary for the server to respond. The server does not need to keep any information about the clients who are making requests and just responds with the state given the parameters in the clients request. This architecture has now become the defacto standard for most large web application interfaces like AWS, [Twitter] and most other web services you can think of. There are many architectural benefits to providing a REST API; for more information, read the wikipedia article on Representational state transfer.

In the case of MTConnect, the Agent has no knowledge of the clients making the request – all context must be passed in the URL and the response will contain all information the client needs to manage the results. In this way we use the REST methodology to reduce the complexity of the Agent but still provide a fully Fault Tolerant and scalable protocol.

Typical Client / Agent Conversation

The sequence of requests for a standard MTConnect conversation will typically begin with the application issuing a probe to determine the capabilities of the device. The result of the probe will provide the component structure of the device and all the available data items for each component.

Once the application determines the necessary data items are available from the Agent, it can issue a current request to acquire the latest values of all the data items and the next sequence number for subsequent sample requests. The application SHOULD also record the instanceId to know when to reset the sequence number in the eventuality of Agent failure. (See Fault Tolerance for a complete discussion of the use of instanceId). Once the current state has been retrieved, the Agent can be sampled at a rate determined by the needs of the application. After each request, the application SHOULD save the nextSequence number for the next request. This allows the application to receive all results without missing a single sample or event and removes the need for the application to compute the value of the from parameter for the next request.

Client and Agent Conversation

The above diagram illustrates a standard conversation between an application and an MTConnect Agent. The sequence is very simple because the entire protocol is an HTTP request/response. The next sequence number handling is shown as a guideline for capturing the stream of Samples, Events, and Condition.

While the above diagram illustrates a standard conversation between an application and an MTConnect Agent, any one application or multiple applications may be having several unre-lated standard conversations occurring simultaneously with the MTConnect Agent, each poten-tially referencing different data or data types and using different portions of the Agent's data ta-ble.

Probe Requests

The MTConnect® Agent MUST provide a probe response that describes this Agent’s devices and all the devices’ components and data items being collected. The response to the probe MUST always provide the most recent information available. A probe request MUST NOT supply any parameters. If any are supplied, they MUST be ignored. The response from the probe will be static as long as the machine physical composition and capabilities do not change, therefore it is acceptable to probe very infrequently. In many cases, once a week may be sufficient.

The probe request MUST support two variations:

  • The first provides information on only one device. The device’s name MUST be specified in the first part of the path. This example will only retrieve components and data items for the mill-1 device.


  • The second does not specify the device and therefore retrieves information for all devices:


The following is an example probe response for 4 Axis Simulator:

Sample Requests

The sample request retrieves the values for the component’s data items. The response to a sample request MUST be a valid MTConnectStreams XML Document.

The diagram below is an example of all the components and data items in relation to one another. The device has one Controller with a single Path, three linear and one rotary axis. The Controller’s Path is capable of providing the execution status and the current block of code. The device has a DataItem with type=”AVAILABILITY”, that indicates the device is available to communicate.

Sample Device Organization
  • The following path will request the data items for all components in mill-1 with regards to the example above (note that the path parameter refers to the XML Document structure from the probe request, not the XML Document structure of the sample):


  • This is equivalent to providing a path-based filter for the device named mill-1:


  • To request all the axes’ data items the following path expression is used:


  • To specify only certain data items to be included (e.g. the positions from the axes), use this form:


  • To retrieve only actual positions instead of both the actual and commanded, the following path syntax can be used:

19.[@type=”POSITION” and @subType=”ACTUAL”]


20.[@type=”POSITION” and @subType=”ACTUAL”]&from=50&count=100

The above example will retrieve all the axes’ positions from sample 50 to sample 150. The actual number of items returned will depend on the contents of the data in the Agent and the number of results that are actual position samples.


All parameters MUST only be given once and the order of the parameters is not important. The MTConnect® Agent MUST accept the following parameters for the sample request:

path - This is an xpath expression specifying the components and/or data items to include in the sample. If the path specifies a component, all data items for that component and any of its sub-components MUST be included. For example, if the application specifies the path=//Axes, then all the data items for the Axes component as well as the Linear and Rotary sub-components MUST be included as well.

from - This parameter requests Events, Condition, and Samples starting at this sequence number. The sequence number can be obtained from a prior current or sample request. The response MUST provide the nextSequence number. If the value is 0 the first available sample or event MUST be used. If the value is less than 0 (< 0) an INVALID_REQUEST error MUST be returned.

count - The maximum number of Events, Condition, and Samples to consider, see detailed explanation below. Events, Condition, and Samples will be considered between from and from + count, where the latter is the lesser of from + count and the last sequence number stored in the agent. The Agent MUST NOT send back more than this number of Events, Condition, and Samples (in aggregate), but fewer Events, Condition, and Samples MAY be returned. If the value is less than 1 (< 1) an INVALID_REQUEST error MUST be returned.

interval – The Agent MUST stream Samples, Events, and Condition to the client application pausing for interval milliseconds between each part. Each part will contain a maximum of count Events, Samples, and Condition and from will be used to indicate the beginning of the stream.

The nextSequence number in the header MUST be set to the sequence number following the largest sequence number (highest sequence number + 1) of all the Events, Condition, and Samples considered when collecting the results.

If no parameters are given, the following defaults MUST be used:

The path MUST default to all components in the device or devices if no device is specified.

The count MUST default to 100 if it is not specified.

The from MUST default to 0 and return the first available event or sample. If the latest state is desired, see current.

Current Request

If specified without the at parameter, the current request retrieves the values for the components’ data items at the point the request is received and MUST contain the most current values for all data items specified in the request path. If the path is not given, it MUST respond with all data items for the device(s), in the same way as the sample request. The current MUST return the values for the data items, even if the data items are no longer in the buffer.

current MUST return the nextSequence number for the event or sample directly following the point at which the snapshot was taken. This MUST be determined by finding the sequence number of the last event or sample in the Agent and adding one (+1) to that value. The nextSequence number MAY be used for subsequent samples.

The Samples, Events, and Condition returned from the current request MUST have the time-stamp and the sequence number that was assigned at the time the data was collected. The Agent MUST NOT alter the original time, sequence, or values that were assigned when the data was collected.[@type=”POSITION” and @subType=”ACTUAL”]

This example will retrieve the current actual positions for all the axes, as with a sample, except with current, there will always be a sample or event for each data item if at least one piece of data was retrieved from the device.[@type=”POSITION” and @subType=”ACTUAL”]&at=1232

The above example retrieves the axis actual position at a specific earlier point in time - in this case, at Sequence Number 1232.


The MTConnect® Agent MUST accept the following parameter for the current request:

path - same requirements as sample.

interval - same requirements as sample. MUST NOT be used with at.

at - an optional argument specifying the MTConnect protocol sequence number. If supplied, the most current values on or before the sequence number MUST be provided. If at is not provided, the latest values MUST be provided. at MUST NOT be used with the interval as this will just return the same data set repeatedly.

If no parameters are provided for the current request, all data items MUST be retrieved with their latest values.

Getting the State at a Sequence Number

The current at allows an application to monitor real-time conditions and then perform causal analysis by requesting the current values for all the data items at the sequence number of interest. This removes the requirement that the application continually poll for all states and burden the server and the network with unneeded information associated with faults or other abnormal conditions.

The following table is a list of events and conditons:

Events and Conditions