Skip to main content

Conditions

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 regular data items.

Conditions are data items that describe one or more alarm codes. Each alarm code is associated with a message describing the alarm that the code represents. At any given time, a code can be reported in a FAULT, WARNING, or NORMAL state.

There are a couple ways to define alarm codes in an adapter scripts.

Static Conditions​

Simple configuration​

conditions:
  coolant-low:
    message: Coolant level is low
    value:
      FAULT: coolant-in < 1.5

In simple configurations, only one alarm code is supported on the data item, and the name of the alarm 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 configuration​

conditions:
  coolant-low:
    - code: c01
      message: Coolant level is low
      value:
        WARNING: coolant-in < 1.5 and coolant-in >= 1.0
    - code: c02
      message: Coolant level is critically low
      value:
        FAULT: coolant-in < 1.0

When multiple alarm 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 alarm 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 alarm 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.

Variables in codes and messages​

In some configurations, condition information may be coming from sources that provide a code or message to report, and so the codes and message strings are not known exactly ahead of time.

Codes and messages can both be specified as string expressions, and thus contain variable references using the following syntax:

${variablename}

The following example shows this use in an EtherNet/IP integration.

version: 2
tags:
  alarm-code: AlarmTagCode
conditions:
  system:
    - code: ${alarm-code}
      message: Alarm ${alarm-code} is active
      value:
        FAULT: alarm-code != ""

Variable-based codes and messages are part of the same structure as multi-code configuration described earlier.

Condition Sources​

Passthrough condition sources​

When an adapter script is being written with an MTConnect adapter or MTConnect agent source, a special option is available to pass through MTConnect conditions as they are received.

Instead of declaring a list of explicit codes under a new condition key, write in a source property that refers to an existing declared mtconnect key that is known to be a condition. One potential use for this would be to rename a condition key. Another use would be filtering out codes, covered in another section below.

version: 2
mtconnect-passthrough: false
declare-keys:
  - sys11 # an incoming key known to be an MTConnect condition
conditions:
  system:
    source: sys11

Array condition sources​

Several connectivity types such as OPC-UA and EtherNet/IP may report alarm states in the form of an array of active alarm codes, an array or active alarm messages, or both. If these arrays are referenced in the tags list, they can be referenced in a condition using the code-list and message-list properties.

version: 2
tags:
  alarm-codes:
    path: ns=2;s=ActiveAlarmCodes
conditions:
  system:
    source:
      code-list: alarm-codes
      message-list: alarm-codes

In the above example, an OPC-UA data source provides a list of active codes only. In the condition definition, the list is referenced by both the code-list and message-list. The message value of any active alarm will simply repeat the value of its code.

It's possible to further process the data with limited array processing support in adapter scripts. For example, we could create a new messages variable derived from the alarm-codes tag that creates more complete messages.

version: 2
tags:
  alarm-codes:
    path: ns=2;s=ActiveAlarmCodes
variables:
  alarm-messages:
    - source: alarm-codes
    - map:
      - expression: concat("Alarm code ", this, " active")
conditions:
  system:
    source:
      code-list: alarm-codes
      message-list: alarm-messages

The map operation allows a sub-list of operations to be applied to each of the elements in alarm-codes individually.

The opposite case may occur where only full message strings are provided by the data source, and a set of consistent codes need to be synthesized so they can be referenced in the MachineMetrics app. One possible solution looks like this:

version: 2
tags:
  alarm-messages:
    path: ns=2;s=ActiveAlarmMessages
variables:
  alarm-codes:
    - source: alarm-messages
    - map:
      - hash: md5
      - max-length: 8
conditions:
  system:
    source:
      code-list: alarm-codes
      message-list: alarm-messages

This will create a corresponding “code” for each message that looks like a random 8-character string, but the code produced will always be the same for a given message string.

A third, optional property available on array sources is level-list. The list must have the same number of elements as the code and message lists and the elements must be in the same order. The allowed values in this list are NORMAL, WARNING, and FAULT corresponding to the MTConnect condition levels. Using a level-list allows different codes to be presented at different levels (warning or fault), or to be cleared/ignored (normal). Machine sources are unlikely to produce these values directly, so you will likely need to use the map operation to synthesize the values from other available data.

version: 2
tags:
  alarm-codes:
    path: ns=2;s=AlarmCodes
  alarm-messages:
    path: ns=2;s=AlarmMessages
  alarm-active:
    path: ns=2;s=AlarmState
variables:
  alarm-levels:
    - source: alarm-active
    - map:
      - state:
        - FAULT: this == 'triggered'
        - NORMAL: true
conditions:
  system:
    source:
      code-list: alarm-codes
      message-list: alarm-messages
      level-list: alarm-levels

Code filtering​

When an adapter script is using the source property on a condition, either for an MTConnect passthrough or for array sources, it's possible filter out codes from those sources so that they don't get reported. The two properties available for this are allow-codes and deny-codes, and each takes a list of strings or patterns to match against. When an allow-codes list is specified, only codes matching the list will be allowed through, When a deny-codes list is specified, all codes will be allowed through except those matching the list.

version: 2
mtconnect-passthrough: false
declare-keys:
  - sys11 # an incoming key known to be an MTConnect condition
conditions:
  system:
    source: sys11
    deny-codes:
      - door_alarm
      - test_*      # wildcard patterns with *
      - /E\d{2}/    # regular expressions

The code lists support simple strings, wildcard matches with asterisks (*), and full regular expression patterns by surrounding the pattern in forward slashes (//).

Level Reclassification​

Similar to code filtering, it's possible to reclassify the condition level of codes using the properties reclassify-warning and reclassify-fault. The properties take the same type of code list as the allow-codes and deny-codes properties, but any codes that match the list will instead have their level reclassified.

  • reclassify-warning: Any matching code in the FAULT state will be reclassified as a WARNING.
  • reclassify-fault: Any matching code in the WARNING state will be reclassified as FAULT.

Codes in either the NORMAL or UNAVAILABLE states will not be affected.

version: 2
mtconnect-passthrough: false
declare-keys:
  - sys11 # an incoming key known to be an MTConnect condition
conditions:
  system:
    source: sys11
    reclassify-fault:
      - door_alarm
      - test_*      # wildcard patterns with *
      - /E\d{2}/    # regular expressions
  # A single wildcard entry can be used to match all codes on a condition
  all-warnings:
    source: sys11
    reclassify-warning:
      - '*'

Overrides​

It's possible to override individual codes and messages on a condition using the overrides section. Overrides is a list of one or blocks that make up an override rule. Each block has two main components: matching and overrides.

An override block can contain a match-code or match-message property (or both). The match values are the same as the values used in code and message filtering. They can be either a fixed string, a wildcard string (using the * character as the wildcard), or a regular expression. If both match-code and match-message are provided, both matches must be valid for the rule to apply.

An override block can contain an override-code or override-message property (or both). When the matching properties pass for a given condition update, the override properties replace the code or message values on the update. The overrides take string expressions, so variables or other identifiers can be included by utilizing the ${expr} syntax. The special keyword this is available in expressions to represent the current code or message alue.

When more than one override block is present in the overrides section, the blocks will be evaluated in the same order they are listed in the script. Once one of the blocks passes the match rules, the rest of the blocks will be skipped for that update. Specific rules should be listed ahead of more general rules.

version: 2
mtconnect-passthrough: false
declare-keys:
  - tool_width
  - sys11 # an incoming key known to be an MTConnect condition
conditions:
  system:
    source: sys11
    overrides:
      - match-code: X01
        override-message: ${this} tool width = ${tool_width}
      - match-code: X02
        override-code: E02
      - match-message: /.*coolant.*/
        override-message: Coolant alarm - ${this}