Skip to main content

Data Items

Data is streamed to MachineMetrics in the form of MTConnect data items. At its most basic definition, an MTConnect data item represents a key and value pair, where the key is the name of the data item and the value is a discrete sample or state value that is changing over time. A data item is mapped to a type on MachineMetrics, which influences how it can be displayed, plotted, reported, or acted upon. Within an adapter script however, data does not have a meaningful type outside of its basic data type, such as a number or string.

Most data items are declared in a block called data-items. This block is a simple list that declares any other identifiers in the adapter script that should be exported to MachineMetrics. There is also a legacy version of the data-items block that allows naming and logic to be incorporated.

Conditions represent a special case and these are declared in a separate block called conditions. Conditions carry extra metadata such as error codes and messages.

Data Items Block​

The preferred way to specify data items is as a list of identifier names. An identifier is any other variable or data source that could be referenced in an expression. See the Expressions document for more information on expressions and valid identifiers.

An example of data items presented in the context of a broader adapter script:

tags:
  oil_temp: Local:System.oil_temperature
  oil_pump: Local:System.oil_pump_running
  coolant_temp: Local:System.coolant_temperature
  running: Local:System.running
variables:
  system_ready:
    - expression: oil_temp > 40 and oil_pump == 1
  execution:
    - state:
      - ACTIVE: running and system_ready
      - READY: system_ready
      - STOPPED: true
data-items:
  - oil_temp
  - coolant_temp
  - system_ready
  - execution

In this example, six identifiers are declared. Four come from an Ethernet/IP data source, and two are variables defined in the script. Four of the identifiers are listed in the data-items block, so only those will be sent to MachineMetrics (oil_pump and running will be excluded).

When an identifier is listed in the data-items block, the name of the identifier will also be the key name of the item sent to MachineMetrics. If you want a different key name, either change the identifier name in the rest of the config to match, or define a new variable with the desired name, and its source set to the identifier you originally wanted to export. You can also use the shorthand syntax, data item expressions.

Data Item Expressions​

As a convenience, a data item line can be given an expression to calculate its value. This decouples the value from the name of the data item, and provides an easy way to output properties of a an object.

It's important to note that any expression results on a data item line are not available within the rest of the script. If you need a result that you can use in other variables or conditions, write it as a variable instead.

A revised example where the tags from the data source are complex objects:

tags:
  oil: Local:System.oil
  coolant: Local:System.coolant
data-items:
  - oil_temp: oil.temperature
  - coolant_temp: coolant.temperature
  - system_ready: oil.temperature > 40 and oil.pump == 1
  - execution

Legacy Data Items Block​

There is a legacy data items format that may be encountered in older scripts. Compared to the list version, it is much more expressive in being able to specify an exact key name for data items, derive values from expressions, or pick a textual state value based on a list of conditions. While this is more powerful, the added expressive power duplicates a subset of the variables section and the definitions are often redundant. For example:

data-items:
  oil_temp:
    value: oil_temp
  coolant_temp:
    value: coolant_temp

The legacy data items definitions come in two flavors: value expressions and value state machines.

Value Expressions​

Every data item has a value attribute, which is an expression that can reference one or more other identifiers in the config. Beware, data-items are not themselves valid identifiers!

A data item value expression will only be evaluated if one of the underlying identifiers has changed. If the result of the expression is different than the last evaluation of the expression, then the change in the data item will be streamed to MachineMetrics.

Here is one way the earlier data items block example (without execution) could be represented in the legacy format:

tags:
  oil_temp: Local:System.oil_temperature
  oil_pump: Local:System.oil_pump_running
  coolant_temp: Local:System.coolant_temperature
data-items:
  oil_temp:
    value: oil_temp
  coolant_temp:
    value: coolant_temp
  system_ready:
    value: oil_temp > 40 and oil_pump == 1

Assuming that the system_ready variable was not needed for another expression in the adapter script, it's able to be inlined in the data item value definition. Redundancy creeps into the other definitions.

info

Data Item Expressions are able to capture most of the expressive power of the legacy value expressions.

Value State Machines​

Many data items in MTConnect represent state. For example, a cutting data item can be in an ON or OFF state. An execution data item can be in an ACTIVE, READY, INACTIVE, or STOPPED state, among several others. To support these data items, the value attribute can be specified as an object, where each key is an MTConnect state appropriate for the data item, and the value is an expression.

When an input identifier changes, each state expression will be evaluated in the order written until one of them returns a true value, at which point that state will become the new value of the data item. You can take advantage of this fall-through behavior to ensure a default state at the end if no other states match. If no expression returns true, the assigned state value will be UNAVAILABLE.

info

State behavior can be replicated in a variable definition by using the state operation in A variable.

Some examples are:

execution:
  value:
    ACTIVE: spindle-1 or spindle-2
    READY: not (spindle-1 or spindle-2)
# Equivalent to the previous example
execution:
  value:
    ACTIVE: spindle-1 or spindle-2
    READY: true 
execution:
  value:
    STOPPED: equalText(exec-tag, 'STOPPED') or feed-rate == 0
    ACTIVE: equalText(exec-tag, 'ACTIVE')
    READY: true 
spindle_rotating:
  value:
    ON: spindle-1
    OFF: not spindle-1