OPC-UA Syntax Reference

The opc-ua device profile connects to an OPC-UA server to read data nodes, alarms and events, with several security and authentication modes. This page lists every option the profile accepts. For the parts of an adapter script that are not specific to OPC-UA (variables, data-items, conditions, expressions), see Adapter Scripts.

Tags

The tags block names each OPC-UA node to read. The tag name becomes a key you can use in variables and data-items.

Attributes

• path — required — OPC-UA node ID
  Node to read. Format is ns=<namespace>;<type>=<id>, where type is i (numeric), s (string), g (GUID) or b (base64 bytes). ns= may be omitted for namespace 0.

• index — optional — n or n:m, integers ≥ 0, n ≤ m
  For array nodes, read only element n, or elements n through m. Several tags can read different elements of the same array by sharing a path with different indexes.

• property — optional — member name
  For nodes with a structured value, report only this member.

A tag that only needs a path can use the shorthand form name: <node ID>.

Example

tags:
  # Shorthand
  execution: ns=2;s=/Channel/State/progStatus
  # Standard form
  part-count:
    path: ns=2;s=/Channel/State/actParts
  spindle-load:
    path: ns=2;s=/Nck/Spindle/driveLoad
    index: 1
  # Two elements of one array
  feed-override:
    path: ns=3;s=Controller/Overrides
    index: 2
  spindle-override:
    path: ns=3;s=Controller/Overrides
    index: 3
  axis-loads:
    path: ns=2;s=/Nck/MachineAxis/aaLoad
    index: 1:3
  program:
    path: ns=3;i=5012
    property: name

Read options

Attributes

• read-mode — optional, default subscription — subscription, polling
subscription asks the server to send values when they change. polling reads every tag once each scan-interval; it is not suited to large numbers of tags. Alarms and events always use a subscription, whichever mode is set.

• scan-interval — optional, default 1.0 — seconds, > 0
  In polling mode, the time between reads. In subscription mode, the sampling and publishing interval requested from the server.

• force-read-on-connect — optional, default false — true, false
  Read every tag once when the adapter starts and after each reconnect. Use it for servers that don't send current values when a subscription opens.

Example

read-mode: polling
scan-interval: 0.5
force-read-on-connect: true

Alarms and conditions

OPC-UA Alarms & Conditions are reported as MTConnect conditions. They are enabled by the opcua-conditions block, or the older opcua-condition-key. Without either, the adapter does not subscribe to alarms.

Attributes

• key — required — name
  Key of the condition the alarms are reported under. Include {sourceName} to report each alarm source under its own key, such as "{sourceName}-alarms".

• warning-threshold — optional — number
  Alarms with a severity below this are reported as NORMAL.

• fault-threshold — optional — number
  Alarms with a severity at or above this are reported as FAULT.

• code-format — optional, default {conditionName}_{conditionIdHash} — non-empty string
  Template for the alarm code. See Code format.

• allow-condition-nodes — optional — list of rules
  Only report alarms whose condition ID matches a rule. See Allow and deny lists.

• deny-condition-nodes — optional — list of rules
  Don't report alarms whose condition ID matches a rule.

• allow-source-nodes — optional — list of rules
  Only report alarms whose source node matches a rule.

• deny-source-nodes — optional — list of rules
  Don't report alarms whose source node matches a rule.

Active alarms are reported as WARNING unless a threshold applies. Alarms that are inactive, suppressed, out of service or disabled are reported as NORMAL.

Code format

code-format builds the alarm code from these placeholders:

Placeholder	Value
{conditionName}	Condition name
{conditionId}	Condition node ID
{conditionIdHash}	First 8 characters of the MD5 hash of the condition ID
{sourceName}	Source name
{sourceNode}	Source node ID
{sourceNodeHash}	First 8 characters of the MD5 hash of the source node ID
{branchId}	Branch ID of the condition, if the server uses branches
{errorCode}	Value of a custom ErrorCode event field, if the server provides one

Each placeholder is replaced once. Quote the value in YAML when it starts with {.

Allow and deny lists

The four lists filter alarms by condition ID or by source node. Source nodes are coarser: many alarms can share one source node, such as ns=4;s=Oven1/Burner2. An alarm is reported only if it matches at least one rule in each allow list that is set, and no rule in any deny list. Alarms that are filtered out are reported as NORMAL.

Each rule must match the whole node ID. A rule can be:

• A plain string, matched exactly.
• A string with * wildcards, where * matches any characters.
• A regular expression between slashes, such as /ns=\d+;s=Coolant.*/. The flags i, m, u and s may follow the closing slash.

Duplicate rules in a list are an error. An empty allow list matches nothing.

Legacy opcua-condition-key

• opcua-condition-key — optional — name
  Older form of opcua-conditions with only a key. Alarm codes are the plain condition name; thresholds, code-format and filters need opcua-conditions. Ignored when opcua-conditions sets a key.

Examples

Report every alarm under one condition, as WARNING while active:

opcua-conditions:
  key: system

Map severities to NORMAL, WARNING and FAULT, and build codes from the source and condition names:

opcua-conditions:
  key: system
  warning-threshold: 200
  fault-threshold: 700
  code-format: "{sourceName}_{conditionName}"

Report each alarm source under its own condition key:

opcua-conditions:
  key: "{sourceName}-alarms"

Only report alarms from the oven and coolant systems, leaving out one condition and one burner:

opcua-conditions:
  key: system
  allow-condition-nodes:
    - ns=4;s=Oven1/*
    - /ns=\d+;s=Coolant.*/
  deny-condition-nodes:
    - ns=4;s=Oven1/Burner1/FlameLoss
  deny-source-nodes:
    - ns=4;s=Oven1/Burner2

Legacy form, equivalent to the first example but with plain condition-name codes:

opcua-condition-key: system

Events

The opcua-events block subscribes to OPC-UA events and makes each one available to the script under the name you give it. Each event's value is an object holding EventId (as hex text) and the fields you select. It changes each time a matching event arrives, so it is typically used as a variable source.

Requires adapter version 1.65.1 or later.

Attributes

• type — required — event type node ID
  Event type to subscribe to. Its subtypes are included.

• notifier — optional, default i=2253 (Server) — node ID
  Node to receive events from.

• fields — optional — map of key → browse path
  Event fields to report, under the given keys. See Event fields.

• auto — optional, default false — true, false
  Also report every top-level field of the event type, its subtypes and its supertypes, other than those BaseEventType defines, keyed by browse name. Characters other than letters, digits, _ and - become _. A key in fields replaces an automatic field of the same name. An automatic field whose key clashes with a base field or another automatic field is skipped, with a warning in the adapter log.

• where — optional — map of field → value
  Only report events whose fields equal every given value. Values are strings, numbers or booleans. See Filtering events.

Event fields

Field keys must start with a letter or _ and contain only letters, digits, _ and - (not ending in -), so they can be used in expressions such as cycle.program. They can't reuse a base field name: EventId, EventType, SourceName, SourceNode, Time, Message, Severity or EventTypeName.

Field paths use OPC-UA RelativePath text syntax:

• Each segment is a browse name, optionally prefixed with its namespace index, such as 3:ProgramName.
• Separate segments with / or ., for example /3:ActiveState.0:Id. The leading separator is optional.
• Escape the characters / . < > : # ! & inside a name with &, for example 3:Run&.Count.

Filtering events

where keys can be a base field (EventId, EventType, SourceName, SourceNode, Time, Message, Severity, EventTypeName), a key from fields, or a member of either, such as state.Id. With auto: true, automatic field keys can be used too. Base fields other than EventId are only used for filtering and are not reported.

Event names

An event name must be a valid adapter script name and can't be the same as a tag, the alarm key, a generator, or a reserved name.

Examples

Report every field of a custom event type, from any source on the server:

opcua-events:
  tool-change:
    type: ns=3;s=ToolChangeEventType
    auto: true

Pick out named fields, and use the event as a variable source that changes on each completed cycle:

opcua-events:
  cycle:
    type: ns=3;s=CycleCompleteEventType
    fields:
      program: 3:ProgramName
      parts: 3:PartCount

variables:
  cycle-complete:
    - source: cycle
    - value-change

data-items:
  - program: cycle.program
  - cycle-complete

Receive events from one machine's node, and only those from one source whose state is active:

opcua-events:
  press-job:
    type: ns=3;s=JobEventType
    notifier: ns=3;s=Line1/Press4
    fields:
      job: 3:JobName
      active: /3:ActiveState.0:Id
    where:
      SourceName: Press4
      active: true

Connection security

Security mode and policy secure the connection itself. They are separate from authentication. The mode and policy must be a pair the server supports.

Attributes

• security-mode — optional, default None — None, Sign, SignAndEncrypt
Sign signs messages; SignAndEncrypt signs and encrypts them.

• security-policy — optional, default None — None, Basic256Sha256, Aes128_Sha256_RsaOaep, Basic128Rsa15, Basic256
  Algorithms used to sign and encrypt. Basic256Sha256 is the most widely supported. Basic128Rsa15 and Basic256 are obsolete.

With security-mode: None the connection is unsecured, and the policy should also be None. With Sign or SignAndEncrypt, the server must trust the adapter's client certificate.

Example

security-mode: SignAndEncrypt
security-policy: Basic256Sha256

Authentication

Without credentials, the adapter connects anonymously.

Attributes

• username — required with password — text
  User name. Used only when password is also set.

• password — required with username — text
  Password. Used only when username is also set.

• user-certificate-path — required with user-private-key-path, unless either is default — default, file name or absolute path
  X.509 user certificate.

• user-private-key-path — required with user-certificate-path, unless either is default — default, file name or absolute path
  Private key for the user certificate.

If a user name and password and a certificate are all set, the user name and password are used.

Certificate authentication

Setting either path to default makes the adapter use its own self-signed user certificate, which it creates on first use. The server must be set up to accept that certificate. Prefer default, since the private key then never leaves the adapter.

To use your own certificate, set both paths. A file name is looked up in the adapter's certificate store; an absolute path is used as is. Contact MachineMetrics Support to have the files placed on the edge device.

Examples

# User name and password
username: mmuser
password: secret

# Adapter's own certificate
user-certificate-path: default
user-private-key-path: default

Reserved names

These names are used by the adapter and can't be used for an event:

• device-connected
true while the adapter is receiving data from the server, false once deliveries stop or the connection is lost. Can be used in scripts like any other key.