OPC DA

Warning

The OPC DA protocol may require root permissions in some constellations. If you experience problems with running this protocol, please make sure to install your service on an agent with root permissions as described in agent orchestration.

The OPC Data Access (OPC DA) specification is an older protocol specification for real-time data from PLCs and devices, but nowadays this is mostly being superseded by OPC UA.

In OPC DA, the endpoints are called tags and are referenced to by plain strings.

Endpoints can either refer to one single tag, using the property tag, or multiple tags in one network query, using the property tags.

Currently read, write and subscribe operations are possible.

Additionally, browsing all available data is available, too, by using the property browse and sending a message to the req sub-topic of this endpoint.

Connection Properties

host (string, required)

Hostname or IP of the OPC DA server

Example: "192.168.0.1"

port (integer)

Port of the OPC DA server

Default: 135

domain (string)

Microsoft Windows domain of the OPC DA server

Default: "WORKGROUP"

username (string, required)

Username for OPC DA server (usually a user on the Windows computer of the OPC DA server)

Example: "user"

password (string, required)

Password for the user on the OPC DA server (usually the password of the Windows user)

Example: "user"

classId (string, required)

Microsoft Windows DCOM class ID of the OPC DA server

Default: "F8582CF2-88FB-11D0-B850-00C0F0104305"

Example: "F8582CF2-88FB-11D0-B850-00C0F0104305"

group (string)

OPC DA group name for the tags that will be accessed

Default: "Connectware Group"

Example: "Some Name"

timeout (integer)

Timeout, in milliseconds

Default: 5000

Examples: 2000, 5000, 10000

comVersionMinor (integer)

The minor part of the DCOM protocol version. The major protocol version is fixed at 5, but the minor version can be configured to choose between 5.7 (default) or the older 5.4.

Default: 7

Examples: 4, 7

connectionStrategy (object)

If a connection attempt fails, retries will be performed with increasing delay (waiting time) in between. The following parameters control how these delays behave.

Properties of the connectionStrategy object:

initialDelay (integer)

Delay (waiting time) of the first connection retry (in milliseconds). For subsequent retries, the delay will be increased according to the parameter incrementFactor which has a default value of 2.

Default: 1000

Additional restrictions:

  • Minimum: 1000

maxDelay (integer)

Maximum delay (waiting time) to wait until the next retry (in milliseconds). The delay (waiting time) for any subsequent connection retry will not be larger than this value. Must be strictly greater than initialDelay.

Default: 30000

incrementFactor (integer)

The factor used to increment initialDelay up to maxDelay. For example if initialDelay is set to 1000 and maxDelay to 5000 the values for the delay would be 1000, 2000, 4000, 5000.

Default: 2

Additional restrictions:

  • Minimum: 2

Endpoint Properties

tag (string)

The name of the tag that should be accessed. Use this property for a single tag, or alternatively the tags property for multiple ones.

Examples: "Random.Real4", "Triangle Waves.Int2"

type (string, enum)

The type of the tag

This element must be one of the following enum values:

  • DATE

  • CURRENCY

  • VARIANTBODY

  • VARIANT

  • DOUBLE

  • COMARRAY

  • BOOLEAN

  • SHORT

  • INTEGER

  • FLOAT

  • STRING

  • UUID

  • BYTE

  • LONG

  • CHARACTER

  • INTERFACEPOINTER

  • INTERFACEPOINTERBODY

  • DISPATCH

  • COMOBJECT

  • POINTER

  • STRUCT

  • UNION

  • COMSTRING

  • UNSIGNEDBYTE

  • UNSIGNEDSHORT

  • UNSIGNEDINTEGER

  • DUALSTRINGARRAY

tags (array)

An array of names of the tags that should be accessed. Use this property for multiple tags, or alternatively tag for a single one.

The object is an array with all elements of the type string.

Example: ["Random.Real4","Triangle Waves.Int2"]

browse (string, enum)

The method for browsing this OPC DA server. Use this property if the endpoint should serve as a browse endpoint, alternative to the tag or tags endpoint.

This element must be one of the following enum values:

  • flat

  • tree

Default: "flat"

interval (integer)

Polling interval in ms for subscriptions

Default: 1000

cronExpression (string)

The Cron expression used to poll the endpoint. (For examples, see: https://github.com/node-cron/node-cron)

Examples: "1,2,4,5 * * * *", "1-5 * * * *", "*/2 * * * *", "* * * January,September Sunday"

Input Format

To write data to a particular tag, first you need to define a write endpoint with a tag and type properties defined.

You can see an example of such endpoint on the provided commissioning file below.

Once you have a proper endpoint, you will need to send the following message with the value you want to write to the /set sub-topic of the endpoint, i.e. if there is an endpoint named myEndpoint, you need to send a message to the topic myEndpoint/set with the following payload:

{
  "value": 228736
}

Output Format

If data is read from OPC DA the output will be provided as JSON object

{
  "timestamp": "<timestamp as given from OPC DA>",
  "value": "value"
}

The timestamp as given from OPC DA is usually given in ISO 8601 form, which is a string of the following form: Year-Month-Date, then a T separator, followed by hour:minutes:second, followed by a period, and the milliseconds, and a Z suffix. Example: 2024-02-15T15:57:36.278Z

The value is in one of two forms, depending on whether this endpoint requested a single tag or multiple tags.

If a single tag was requested, the value is just the literal value of the tag, such as an integer number. Example:

{ "timestamp": "2021-11-15T16:12:22.835Z", "value": 58.420013427734375 }

If multiple tags were requested, the value is a JSON object with the tag names as keys, and the tag’s values as values. Example:

{
  "timestamp": "2022-04-15T16:12:23.679Z",
  "value": {
    "Triangle Waves.Int4": 24690,
    "Triangle Waves.Real4": 63.50001525878906
  }
}

Browsing the tags

When intending to explore the available tags, the browse property of the endpoint is useful. To use this, define a read endpoint with the property browse: 'flat' as the only addressing property. (Alternatively, browse: 'tree' can be used, too.) To browse the tag list, send an empty MQTT message to the topic of the endpoint but with the suffix /req (“request”). The Connectware will run the browsing and return the result on the endpoint topic with the suffix /res.

For flat browsing, the result value is an array of strings, which are just the tag names. Example:

{
  "timestamp": "2022-04-15T16:12:23.679Z",
  "value": [
    "@ClientCount",
    "Bucket Brigade.ArrayOfReal8",
    "Bucket Brigade.ArrayOfString",
    "Bucket Brigade.Boolean",
    "Bucket Brigade.Int1",
    "Bucket Brigade.Int2"
  ]
}

For tree browsing, the result value is a JSON object tree structure representing the tag tree on the server. Example:

{
  "timestamp": "2022-04-15T16:12:23.679Z",
  "value": {
    "@ClientCount": "@ClientCount",
    "Simulation Items": {
      "Bucket Brigade": {
        "ArrayOfReal8": "Bucket Brigade.ArrayOfReal8",
        "ArrayOfString": "Bucket Brigade.ArrayOfString",
        "Boolean": "Bucket Brigade.Boolean",
        "Int1": "Bucket Brigade.Int1",
        "Int2": "Bucket Brigade.Int2"
      }
    }
  }
}

Example Commissioning File

Download: opcda-example.yml

 1---
 2description: >
 3
 4  Accessing an OPC DA server
 5
 6metadata:
 7
 8  name: Using OPC DA Server
 9  version: 1.0.0
10  icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg
11  provider: cybus
12  homepage: https://www.cybus.io
13
14parameters:
15
16  opcdaHost:
17    type: string
18    description: Hostname or IP of the OPC DA server
19    default: 192.168.0.1
20
21  opcdaUser:
22    type: string
23    default: cybus
24
25  opcdaPass:
26    type: string
27    default: PASSWORD
28
29  initialReconnectDelay:
30    type: integer
31    default: 1000
32
33  maxReconnectDelay:
34    type: integer
35    default: 30000
36
37  factorReconnectDelay:
38    type: integer
39    default: 2
40
41resources:
42
43  opcdaConnection:
44    type: Cybus::Connection
45    properties:
46      protocol: Opcda
47      connection:
48        host: !ref opcdaHost
49        username: !ref opcdaUser
50        password: !ref opcdaPass
51        domain: 'WORKGROUP'
52        classId: 'F8582CF2-88FB-11D0-B850-00C0F0104305'
53        connectionStrategy:
54          initialDelay: !ref initialReconnectDelay
55          maxDelay: !ref maxReconnectDelay
56          incrementFactor: !ref factorReconnectDelay
57
58  multipleTags:
59    type: Cybus::Endpoint
60    properties:
61      protocol: Opcda
62      connection: !ref opcdaConnection
63      subscribe:
64        interval: 2000
65        tags:
66          - 'Triangle Waves.Int4'
67          - 'Triangle Waves.Real4'
68
69  triangleWaveReal4:
70    type: Cybus::Endpoint
71    properties:
72      protocol: Opcda
73      connection: !ref opcdaConnection
74      subscribe:
75        interval: 2000
76        tag: 'Triangle Waves.Real4'
77
78  writeTag:
79    type: Cybus::Endpoint
80    properties:
81      protocol: Opcda
82      connection: !ref opcdaConnection
83      write:
84        tag: 'Triangle Waves.Int4'
85        type: 'INTEGER'
86
87  browse:
88    type: Cybus::Endpoint
89    properties:
90      protocol: Opcda
91      connection: !ref opcdaConnection
92      read:
93        browse: 'flat'