Declaring Inputs

The input section of an adapter script declares what data the script reads. How you write it depends on whether you are building a direct connectivity adapter (reading a machine protocol) or a transform adapter (reading data items from a parent adapter).

Adapter type	Reads from	Input blocks
Direct connectivity	A machine protocol — EtherNet/IP, Modbus, OPC-UA, FANUC FOCAS	tags, registers, coils, pins
Transform	An existing parent adapter's data items	declare-keys, deny-keys, mtconnect-passthrough

warning

These two sets of blocks are not interchangeable. A transform adapter has no hardware addresses, so it cannot use tags, registers, coils, or pins. A direct connectivity adapter has no parent adapter, so it cannot use declare-keys.

---

Transform Adapters: Using declare-keys

Transform adapters pull existing data items from a parent adapter (such as FANUC FOCAS, Modbus, or OPC-UA) and transform them. A transform adapter only sees the data items you explicitly declare.

version: 2

# Pull data items from parent adapter
declare-keys:
  - program_comment
  - tool_number
  - spindle_override

# Transform the data
variables:
  operation:
    - source: program_comment
    - pattern-match:
        pattern: /\(([^)]+)\)/
        group: 1

  tool_status:
    - source: tool_number
    - expression: tool_number > 0

# Output transformed data
data-items:
  - operation
  - tool_status

How declare-keys works:

1. The parent adapter (e.g., FANUC FOCAS) collects data items like program_comment, tool_number, and spindle_override.
2. The transform adapter declares which of those data items it needs.
3. The transform adapter processes them through variables.
4. The transform adapter outputs new or modified data items.

Common use cases:

• Extract an operation number from a program comment using regex
• Parse a part number from a program name
• Convert units or formats
• Combine multiple data items into a derived metric
• Clean or filter data before it reaches MachineMetrics

deny-keys: Excluding Data Items

Use deny-keys to explicitly block data items from being passed through from the parent adapter.

version: 2

# Pull specific data items
declare-keys:
  - program_comment
  - execution
  - part_count

# Exclude specific data items from parent adapter
deny-keys:
  - raw_alarm_code  # Don't pass through raw codes
  - debug_flag      # Internal use only

variables:
  operation:
    - source: program_comment
    - pattern-match:
        pattern: /\(([^)]+)\)/
        group: 1

data-items:
  - operation
  - execution
  - part_count

When to use deny-keys:

• Block internal or debug data items from reaching MachineMetrics
• Prevent duplicate or conflicting data items
• Filter out raw data that a transformed version replaces
• Control exactly which data items are exposed

warning

Defining a filtered condition does not suppress the original condition from the parent adapter. To replace rather than supplement it, list the original in deny-keys as well.

mtconnect-passthrough: Passing Parent Data Through

Set mtconnect-passthrough: true to automatically pass every data item from the parent adapter through the transform adapter, in addition to any transformed data items.

version: 2

# Pass all parent adapter data items through
mtconnect-passthrough: true

# Only declare keys you need to transform
declare-keys:
  - program_comment

# Transform specific data items
variables:
  operation:
    - source: program_comment
    - pattern-match:
        pattern: /\(([^)]+)\)/
        group: 1

# Output transformed data (parent data also passed through)
data-items:
  - operation

How it works:

1. The parent adapter collects many data items (50+ is typical for FANUC FOCAS).
2. The transform adapter sets mtconnect-passthrough: true.
3. All parent data items pass to MachineMetrics automatically.
4. The transform adapter only needs declare-keys for the items it intends to transform.
5. Both the original parent data and the transformed data are available in MachineMetrics.

This avoids having to list every data item you want to preserve, which keeps transform scripts short when you are modifying one field out of many.

Example: Transform One Item, Keep the Rest

# Parent FOCAS adapter provides 50+ data items.
# We only want to transform program_comment → operation,
# but we want all other FOCAS data items (spindle_speed, tool_number, etc.)

version: 2
mtconnect-passthrough: true  # Pass everything through

declare-keys:
  - program_comment  # Only declare what we're transforming

variables:
  operation:
    - source: program_comment
    - pattern-match:
        pattern: /\(([^)]+)\)/
        group: 1

data-items:
  - operation  # New data item added to the parent's 50+ items

All parent FOCAS data items are sent to MachineMetrics, plus the new operation data item.

---

Direct Connectivity Adapters

Direct connectivity adapters read data straight from a machine protocol. The input blocks below are only valid in this adapter type.

EtherNet/IP Tags

version: 2
slot: 1
scan-interval: 0.25
tags:
  recipe_loaded: RecipeLoaded
  mode_auto: Module10.ModeAuto
  peak_force: Program:Station1.Values.Reals[0]

Modbus Registers and Coils

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

See Modbus/TCP Connectivity for how to determine addresses and types from a control's Modbus map.

OPC-UA Tags

version: 2
tags:
  spindle-speed: ns=2;s=Spindle.Speed
  coolant-level: ns=2;s=Coolant.Level
  program: ns=2;s=Controller.Program

See OPC-UA Connectivity for how to browse a server and find node IDs.

Key Naming Rules

• Use lowercase with hyphens: spindle-speed, part-count
• Avoid spaces and special characters
• Names become the identifiers used throughout the rest of the script

---

Next Steps

• Variables — transform the data you have declared
• Data Items — declare what gets sent to MachineMetrics
• Examples — complete scripts using each input style