Skip to main content

Introduction

Adapter scripts are a common configuration and logic language used by several MachineMetrics connectivity types. At their most basic, they can be used just to configure connectivity, such as specifying which tags to read on an OPC-UA connection, or which registers to read on a MODBUS connection. Adapter scripts can also be used to further manipulate or synthesize data, which can be exported as new data items or conditions (alarms).

Adapter scripts are YAML documents, which is a data markup language commonly used in software configuration. Check out our own YAML Guide for an introduction to YAML syntax. YAML has an extensive feature set, but adapter scripts only need to use a basic subset of those capabilities.

Structure​

Each adapter script can be broadly separated into three main sections:

  • Input
  • Transformation
  • Output

The input section consists of everything related to connectivity. Depending on the specific connectivity type, this can include configuring the connection or device. It may also include specifying or configuring the individual pieces of data being read from the connection. Any piece of data configured in this section will be associated with an identifier that can be used in the transformation or output sections.

The transformation section is where new variables can be defined, which can be used to transform data. Variables are able to read the values of other variables or the identifiers from the input section.

The output section defines what data will be sent to MachineMetrics in the form of data items and conditions. Input data and variables do not automatically get exported; they must be listed in these blocks.

Examples​

Here are a couple examples of full adapter scripts, with a few comments included to denote the major sections described above. The order of the top-level blocks like tags, variables and data-items within the script are not important, but they typically follow an input -> transform -> output order by convention, as it aids in understanding how data flows through the script.

Example: EtherNet/IP​

The following example shows an adapter script for an EtherNet/IP connection. It reads a few tags from the PLC, which get assigned names that can be used in the rest of the script. In the transformation section, multiple tag values are used to synthesize execution and controller mode states. These variables and several tags are exported as data items. Tags related to faults are used to create a generic condition.

version: 2

# Input
slot: 1
scan-interval: 0.25
tags:
  recipe_loaded: RecipeLoaded
  mode_auto: Module10.ModeAuto
  fault_ind: Module10.FaultInd
  peak_force: Program:Station1.Values.Reals[0]
  press_force: Program:Station1.Values.Reals[2]
  fault_code: HMI1.StaData.FaultNumber
  fault_msg: HMI1.StaData.FaultDescription

# Transformation
variables:
  execution:
    - state:
      - ACTIVE: mode_auto and fault_ind == 0 and recipe_loaded
      - READY: true
  controller_mode:
    - state:
      - AUTOMATIC: mode_auto
      - MANUAL: true

# Output
data-items:
  - recipe_loaded
  - controller_mode
  - execution
  - press_force
  - force
conditions:
  system:
    - code: gen_fault
      message: Machine is in fault
      value:
        FAULT: fault_ind > 0
    - code: ${fault_code}
      message: ${fault_msg}
      value:
        FAULT: fault_ind > 0

Example: Modbus​

The following example shows an adapter script for a Modbus connection. It reads a few coils and registers from the control, specifying addresses and types that would have been determined by looking at the control's modbus map. The data-items section uses a shorthand syntax to export values with specific names without needing to define a separate variable for each one.

version: 2

# Input
unit-id: 1
byte-order: big
word-order: big
address-space: mixed
coils:
  exec-bit:
    address: 10001
registers:
  counter:
    address: 40005
    type: uint32
  program-name:
    address: 40101
    type: string
    size: 80

# Transformation
variables:
  execution:
    - state:
      - ACTIVE: exec-bit
      - READY: true

# Output
data-items:
  - execution
  - part_count: counter
  - program: program-name