MTConnect Concepts

FairCom Edge MTConnect connector service concepts

The FairCom Edge MTConnect service can connect to and interact with MTConnect agents. This service is included in the FairCom JSON Action API.

MTConnect organizes device data as a hierarchy. A device may have one or more components and each component may deliver sample, event, and condition data. A component may also have child components.

The FairCom MTConnect connector sends an MTConnect request to retrieve data from a device and it returns an MTConnectStreams XML document.

The MTConnectStreams contains one Header and one Streams element. If there is no available data, the Streams element may or may not be empty. It contains zero or more DeviceStream elements.

Each DeviceStream element contains data from a specific device, which is uniquely identified by its uuid attribute. Each DeviceStream element contains zero or more ComponentStream elements, which may contain data from components on a device. If a device has no data, the ComponentStream element may or may not be empty.

Each ComponentStream element contains zero or one of the Samples, Events, and Condition elements, which contain data item elements.

Each DataItem element is defined in the MTConnect device XML file and the device uses this information to generate the data item in the DeviceStream.

DataItem Examples

The following XML definition of a DataItem is from an MTConnect device XML file. Less useful attributes are omitted for better readability.

<DataItem category="EVENT" id="Device1_Avail1" type="AVAILABILITY"/>

The device uses the DataItem definition in the device XML file to generate the DataItem in the DeviceStream as follows:

<Events>
  <Availability dataItemId="Device1_Avail1" timestamp="2010-04-06T06:19:35.153141">AVAILABLE</Availability>
</Events>

Notice the following about the two XML elements:

The DataItem's category of "EVENT" causes the DeviceStream to put the DataItem inside an <Events> element.
The DataItem IDs match.
The "AVAILABILITY" type in the DataItem definition causes the device to output an <Availability> element with a value of AVAILABLE or UNAVAILABLE.

The FairCom MTConnect Connector can ignore everything in the MTConnectStreams XML except for the DataItem elements inside <Events>, <Samples>, and <Condition> elements. The names of the DataItem elements vary and are, thus, unusable. The FairCom Connector must only read the dataItemId attribute and match it to items in its "propertyMapList". It then extracts the value of the DataItem element and converts it into the data type specified by the "dataType" property in the "propertyMapList".

Example MTConnect `"propertyMapList"`

The following "propertyMapList" configures the FairCom MTConnect Connector to retrieve the value of the DataItem identified as "Device1_Act1_1" from the device identified as "Device1". The connector then creates a JSON document that contains a property named "device1Action1PositionInMillimeters" and assigns the value to it.

{
  "propertyMapList": [
    {
      "propertyPath": "device1Action1PositionInMillimeters",
      "deviceUuid": "Device1",
      "dataItemId": "Device1_Act1_1",
      "dataType": "string",
      "defaultValue": "-1",
      "useMtconnectTimestamp": true
    }
  ]
}

If the DataItem specified in the "propertyMapList" does not exist in the MTConnectStreams XML returned by the device, the FairCom Connector uses the -1 value specified by the "defaultValue" property and assigns it to the "device1Action1PositionInMillimeters" JSON property. If the "defaultValue" property is omitted from the "propertyMapList", the FairCom Connector assigns null to the JSON property.

The "dataType" property is a string. Possible values: "string" or "boolean". "string" is the default.

The "defaultValue" property can be any json value.

The "useMtconnectTimestamp" property is a boolean. It defines if we will use the Faircom timestamp (if value is false) or use the value returned from MTConnect (if the value is true). The default is false.

MTConnect startup configuration

Enable the FairCom MTConnect connector service (plugin)

Verify that the MTConnect service is enabled in the FairCom Edge server.

Edit the <faircom>/config/services.json configuration file.
In the "mtconnect" serviceName of the "integrationServices" object, set the "enabled" property to true to enable the MTConnect connector or false to disable the MTConnect service.
Save the changes.
Restart the server for the change to take effect.

Examples

Windows

"integrationServices": [  
  {
    "serviceName": "mtconnect",
    "serviceLibrary": "mtconnectservice.dll",
    "enabled": true  
  }
]

Unix/Linux

"integrationServices": [  
  {
    "serviceName": "mtconnect",
    "serviceLibrary": "mtconnectservice.so",
    "enabled": true  
  }
]

MAC

"integrationServices": [
{
  "serviceName": "mtconnect",
  "serviceLibrary": "mtconnectservice.dylib",
  "enabled": true
}

MTConnect Data Types

MTConnect supports the following native data types

Table 1. MTConnect Data Types

Data Type	Value Range
BOOL	TRUE/FALSE
INT	-32768 to 32767
UINT	0 to 65535
DINT	-2,147,483,648 to 2,147,483,647
UDINT	0 to 4,294,967,295
LINT	-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
ULINT	0 to 18,446,744,073,709,551,616
REAL	0, 1.175495E-38 (Absolute value) to 3.402823E38 (Absolute value)
LREAL	0, 2.22507385850721E-308 (Absolute value) to 1.79769313486231E308 (Absolute value)
STRING	(1 to 32 characters) Example: abcdefghijklmnopqrstuvwxyz123456
WSTRING	(1 to 16 characters) Example: abcdefghijklmnopqrstuvwxyz123456

MTConnect also allows devices to define their own data types.

Example property paths that group related properties

The MTConnect protocol provides metadata about each data value that you collect. This metadata includes the data type, category, device ID, component ID, and data item ID. You may want to include this metadata in the JSON documents generated by FairCom's MTConnect connector. This metadata is useful for troubleshooting and providing context. The MTConnect timestamp is particularly useful because it tracks the actual time the device collected the data.

You can use property paths to organize a JSON document to associate a data value with its metadata. One approach is to nest related properties inside the same JSON object. Another approach is to add the same name prefix to related properties.

The examples in this topic use the following MTConnect XML as the data source for generating JSON results.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

Grouping related properties in the same parent object

The following "createInput" example configures the MTConnect Connector to nest related properties inside a "temperature" object. This approach has the advantage of a short, easy-to-read property names, but the disadvantage of a more complex JSON structure.

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "settings": {
      "host": "195.167.1.5:5000",
      "propertyMapList": [
        {
          "propertyPath": "temperature.value",
          "dataType": "string",
          "mtconnectDeviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
          "mtconnectDataItemId": "X1_Stamper1_Temperature",

          "mtconnectCategoryPropertyPath": "temperature.category",
          "mtconnectComponentNamePropertyPath": "temperature.component",
          "mtconnectDataItemIdPropertyPath": "temperature.dataItemId",
          "mtconnectDataNamePropertyPath": "temperature.dataName",
          "mtconnectDataTypePropertyPath": "temperature.dataType",
          "mtconnectDeviceNamePropertyPath": "temperature.device",
          "mtconnectDeviceUuidPropertyPath": "temperature.deviceUuid",
          "mtconnectSequencePropertyPath": "temperature.sequence",
          "mtconnectTimestampPropertyPath": "temperature.timestamp"
        }
      ]
    },
    "tableName": "mtconnectTable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

When configured with the previous "createInput" example, FairCom's MTConnect Connector collects data and generates a JSON document like the following example.

{
  "temperature": 
  {
    "value": 20.1,
    "category": "SAMPLE",
    "component": "Stamper1",
    "dataItemId": "X1_Stamper1_Temperature",
    "dataName": "Temperature",
    "dataType": "REAL",
    "device": "Device1",
    "deviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
    "sequence": 5,
    "timestamp": "2010-04-06T06:19:35.153141"
  }
}

Grouping related properties using prefixed property names

The following "createInput" example configures the MTConnect Connector to name related properties with the same "temperature" prefix. This approach has the advantage of a simpler JSON structure, but the disadvantage of longer property names.

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "settings": {
      "host": "195.167.1.5:5000",
      "propertyMapList": [
        {
          "propertyPath": "temperatureValue",
          "dataType": "string",
          "mtconnectDeviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
          "mtconnectDataItemId": "X1_Stamper1_Temperature",

          "mtconnectCategoryPropertyPath": "temperatureCategory",
          "mtconnectComponentNamePropertyPath": "temperatureComponent",
          "mtconnectDataItemIdPropertyPath": "temperatureDataItemId",
          "mtconnectDataNamePropertyPath": "temperatureDataName",
          "mtconnectDataTypePropertyPath": "temperatureDataType",
          "mtconnectDeviceNamePropertyPath": "temperatureDevice",
          "mtconnectDeviceUuidPropertyPath": "temperatureDeviceUuid",
          "mtconnectSequencePropertyPath": "temperatureSequence",
          "mtconnectTimestampPropertyPath": "temperatureTimestamp"
        }
      ]
    },
    "tableName": "mtconnectTable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}