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.

tip

You do not have to write a script by hand. Max, the MachineMetrics AI assistant, can generate a complete adapter script from a plain-language description of your hardware or the value you want to extract. See Generating Scripts with AI.

Two Types of Adapter Scripts

Which blocks a script uses depends on where its data comes from. This distinction determines how you declare inputs, so it is worth settling before you write anything.

Type	Reads from	Declares inputs with	Typical use
Direct connectivity	A machine protocol — EtherNet/IP, Modbus, OPC-UA, FANUC FOCAS	tags, registers, coils, pins	Connecting a machine or I/O device for the first time
Transform	The data items of an existing parent adapter	declare-keys, deny-keys, mtconnect-passthrough	Reshaping or deriving data from a machine that already reports

A transform adapter sits on top of a parent adapter and never touches hardware addresses, which makes it the safer choice when a connection already works and you only need to change what it produces. See Declaring Inputs for the full syntax of both.

When to Use Adapter Scripts

Use Case	Example
Combine multiple signals into one state	Spindle + coolant + door → execution state
Count parts from a pulsing signal	Rising edge detection on analog input
Convert sensor values	Temperature C → F, voltage → pressure
Create custom alarms/conditions	Low coolant warning from analog level
Filter or clean data	Ignore warmup programs, remove noise
Derive calculated metrics	Efficiency from multiple inputs
Supply a derived state for a downtime rule	Optionally combine machine signals into a data item for a State rule. Auto downtime evaluates the rule and assigns the downtime reason.

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.

AdapterScript

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.

AdapterScript

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