Note: See the Adapter Script Overview-V2 for an overall look at the V2 adapter scripts.
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 primitive 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
In versions of IO that are recent enough, 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 document:
- expression: oil_temp > 40 and oil_pump == 1
- ACTIVE: running and system_ready
- READY: system_ready
- STOPPED: true
In this example, six identifiers are declared. Four come from an Ethernet/IP data source, and two are variables defined in the adapter script. Four of the identifiers are listed in the data-items block, so only those will be sent to MachineMetrics.
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 adapter script to match, or define a new variable with the desired name, and its source set to the identifier you originally wanted to export.
Legacy Data Items Block
There is a legacy data items format that may be commonly encountered. 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 clearly more powerful, the added expressive power duplicates a subset of the variables section and the definitions are often redundant. For example:
The legacy data items definitions come in two flavors: value expressions and value state machines.
Every data item has a value attribute, which is an expression that can reference one or more other identifiers in the adapter script. Beware, data-items are not themselves valid identifiers! See the Expressions document for more information on expressions and 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:
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.
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.
State behavior can be replicated in a variable definition by using the state operation.
Some examples are:
ACTIVE: spindle-1 or spindle-2
READY: not (spindle-1 or spindle-2)
# Equivalent to the previous example
ACTIVE: spindle-1 or spindle-2
STOPPED: equalText(exec-tag, 'STOPPED') or feed-rate == 0
ACTIVE: equalText(exec-tag, 'ACTIVE')
OFF: not spindle-1
The conditions block is similar to the data-items block but is specific to MTConnect conditions. These have a substantially different representation and behavior than sample data items.
Conditions are data items that describe one or more native codes. Each native code is associated with a message describing the condition that the code represents. At any given time, native code can be reported in a FAULT, WARNING, or NORMAL state.
There are a couple of ways to define native codes in an IO adapter script.
Simple adapter script
message: Coolant level is low
FAULT: coolant-in < 1.5
In simple adapter scripts, only one native code is supported on the data-item, and the name of the native-code itself is optional. If a code parameter is not supplied, it defaults to the name of the data-item (in this case, coolant-low). The value parameter follows the structure of the value state machine description in the previous section. Only FAULT and WARNING values can be specified, and the value will implicitly default to NORMAL if the fault or warning conditions are not met.
In this example, the adapter will send a coolant-low fault when the input representing the coolant level drops below 1.5, and will cancel the fault when the input rises above that value.
Multi-code adapter script
- code: c01
message: Coolant level is low
WARNING: coolant-in < 1.5 and coolant-in >= 1.0
- code: c02
message: Coolant level is critically low
FAULT: coolant-in < 1.0
When multiple native codes are desired, they must be specified using the YAML list syntax, where each block leads with a hyphen and space. The code parameter to name the native code is also mandatory in this case, and these code names will be reported to MachineMetrics along with the message and fault level.
In this example, two native codes are used to split the coolant condition into two levels of severity, reported as a WARNING and FAULT respectively. Both of these codes would be reported under the coolant-low data item. If the >= check were not present on the warning expression, then both of the codes could report their non-normal states simultaneously.
Reach out to firstname.lastname@example.org for additional help.