Version: 2.4

Introduction

The HumanOS® OPC-UA Control Driver is used to access, steer, and manage devices based on OPC-UA protocol.

Driver Configuration

Additional client configurations are not needed for this connector. All settings are put directly into the device information file.

The device driver puts different data to the folder Config\HumanOS.UHAL.OpcUaControl.

Log: log files when activating trace log
CertificateStore: certificates (auto generated, trusted, issuer, rejected)

Device Information

The device information is an XML file specifying the access and commands of an OPC-UA-Device.

The header of the device information declares the

Device id
Driver id (always {F022EE3C-A2A5-428A-B588-46ABACAE39EE})
Base URL as the address, including opc.tcp://

Additional properties help to configure the client-server connection.

Name	Description	Data Type
`opc:SecuritySelection`	Security protocol selection of the endpoints: (None: no security requested (default); BestAvailable: select the best available security)	System.String
`opc:CertificateHandling`	Handling of server certificates: (Strict: only trusted certificates allowed (default); AcceptAll: do not check the certificates)	System.String
`opc:StoreType`	Specifies the store type, either 'Directory' or 'Windows', if left empty the 'Directory' type is taken	System.String
`opc:CertificatePath`	Specifies the certificate path depending on the store type, see HumanOS® OpcUaServer manual for configuration.	System.String
`opc:CertificateTrustedPath`	For StoreType `Windows`: Specifies path to trusted certificates.	System.String
`opc:CertificateIssuerPath`	For StoreType `Windows`: Specifies path to issuer certificates.	System.String
`opc:CertificateRejectedPath`	For StoreType `Windows`: Specifies path to rejected certificates.	System.String
`opc:CertificateSubject`	For StoreType `Windows`: Specifies the application certificate subject name e.g. CN=servercert/O=myorg/DC=myhost	System.String
`opc:AutoGenerateClientCertificate`	Automatically generates a client application certificate for the connecting device client. Default is false.	System.Boolean
`UserName`	[opt] Username to login. Used to authenticate with username and password.	System.String
`Password`	[opt] Password of the user. Used to authenticate with username and password.	System.String
`opc:ClientCertificate`	[opt] Client certificate for authentication. Name of certificate (filename or subject name in windows store)	System.String
`opc:ClientCertificatePassword`	[opt] Client certificate password unused for authentication. Optional password.	System.String
`opc:EnableTraceLog`	[opt] Enabling the trace logger of the UaClient	System.Boolean

Example with basic authentication and no secure connection

{
  "Name": "SiemensOpcUaControl",
  "Id": "6ae9da3f-4606-4c78-9eb3-aa70cebcb571",
  "DriverId": "F022EE3C-A2A5-428A-B588-46ABACAE39EE",
  "Address": "opc.tcp://localhost:48050",
  "Properties": [
    {
      "Name": "UserName",
      "Value": "Guest"
    },
    {
      "Name": "Password",
      "Value": "Guest"
    },
    {
      "Name": "opc:SecuritySelection",
      "Value": "None"
    },
    {
      "Name": "opc:CertificateHandling",
      "Value": "AcceptAll"
    }
  ]
}

Example with store based certificate secure connection

{
  "Name": "SiemensOpcUaControl",
  "Id": "6ae9da3f-4606-4c78-9eb3-aa70cebcb571",
  "DriverId": "F022EE3C-A2A5-428A-B588-46ABACAE39EE",
  "Address": "opc.tcp://localhost:48050",
  "Properties": [
    {
      "Name": "opc:CertificateHandling",
      "DataType": "System.String",
      "Value": "Strict"
    },
    {
      "Name": "opc:StoreType",
      "DataType": "System.String",
      "Value": "Windows"
    },
    {
      "Name": "opc:CertificatePath",
      "DataType": "System.String",
      "Value": "LocalMachine\\My"
    },
    {
      "Name": "opc:CertificateTrustedPath",
      "DataType": "System.String",
      "Value": "LocalMachine\\Trust"
    },
    {
      "Name": "opc:CertificateIssuerPath",
      "DataType": "System.String",
      "Value": "LocalMachine\\Root"
    },
    {
      "Name": "opc:CertificateRejectedPath",
      "DataType": "System.String",
      "Value": "LocalMachine\\Disallowed"
    },
    {
      "Name": "opc:CertificateSubject",
      "DataType": "System.String",
      "Value": "CN=MyCert/O=myorg/DC=myhost"
    },
    {
      "Name": "opc:SecuritySelection",
      "DataType": "System.String",
      "Value": "BestAvailable"
    }
  ]
}

caution

Remember that some locations in 'LocalMachine' require UAC priviledges and therefore can only be accessed if the software runs in an elevated context or the permissions are set correctly on the private key. If e.g. the error 'One or more errors occurred. (Keyset does not exist)' is thrown, this means that either the keyset really doesnt exist, or the permission is not sufficient. To set the permission open certlm, navigate to the certificate, right click on it -> all tasks -> manage private keys and add the user or usergroup with read permission. Remember that locations like 'LocalMachine\Root' cannot be permission edited.

Data Access

The connector supports the data access of OPC-UA server.

Name	Description	Data Type
Id	Id of the data access point	System.Guid
Name	Name of the item	System.String
Address	OPC-UA node id; Examples: (`ns=2;g={13BB68D0-3B8E-42B9-A5BC-993E5B0D49A8}`, `ns=2;s=myItemIdentifier`)	System.String
AccessMode	Read, write or callback flags

Additional OPC-UA properties

Name	Description	Data Type
`opc:SubscriptionId`	Id of the subscription: (MED: Medium speed (default); FAST: Fast speed; SLOW: Slow speed)	System.String

{
  "Id": "1bd0e8c5-1b1f-4018-b1a3-4684cfb221de",
  "Name": "X-Position Absolute",
  "DataType": "System.Double",
  "DataClass": "Stream",
  "Unit": "mm",
  "Address": "ns=2;g={13BB68D0-3B8E-42B9-A5BC-993E5B0D49A8}",
  "Access": {
    "Read": true,
    "Receive": true
  },
  "HistoryMode": {
    "Retention": 1,
    "SampleRate": 2000,
  },
  "Properties": [
    {
      "Name": "opc:SubscriptionId",
      "Value": "MED"
    }
  ]
}

Special Data Nodes

There are special data nodes, provided by the OPC-UA client to outside consumers:

Available: Provides an available flag indicating if the client has a valid connection to the server:
Address: ns=2;s=opc:Available
SignalOfLife: A toggle life bit indicating if the client has a valid an life connection to the server
Address: ns=2;s=opc:SignalOfLife

Alarm and Event Access

Alarm and condition module of OPC-UA server can be accessed using the alarm event source info.

The address is the node id of the main object providing A&C.

{
  "AlarmEventPool": {
    "Id": "FA1611AB-B6C9-4FF4-B34D-BF35E6A44232",
    "Name": "AlarmEventPool",
    "Tasks": [
      {
        "Id": "E669AF07-0991-4A40-A7A4-9D2B2B881D07",
        "Name": "Standard Messages",
        "Address": "ns=2;g={ece37fdf-4862-4543-af23-48ffdb8203c7}"
      }
    ],
    "HistoryMode": {
      "Retention": 1,
      "SampleRate": 1000
    }
  }
}

OEM Message Mapping

The driver supports PLC alarms by mapping source. It is possible to declare multiple alarm sources (tasks) for one alarm address (pool).

As source address only System.Byte[] is allowed.

This example shows three alarm sources with a mapping file:

  "AlarmEventPool": {
    "Id": "FA1611AB-B6C9-4FF4-B34D-BF35E6A44232",
    "Name": "AlarmEventPool",
    "Tasks": [
      {
        "Id": "66d0a44d-83e8-494d-9e15-5af16df60d55",
        "Name": "Alarm Messages",
        "Address": "OEMAlarmEvent",
        "Properties": [
          {
            "Name": "MessageMappingFile",
            "Value": "OEMBitMessages.json"
          },
          {
            "Name": "MessageCount",
            "Value": 8,
            "DataType": "System.Int32"
          },
          {
            "Name": "SourceName",
            "Value": "OpcUa",
            "DataType": "System.String"
          },
          {
            "Name": "StartAddress",
            "Value": "ns=2;s=Demo.Static.Arrays.Byte"
          },
          {
            "Name": "MessageFormat",
            "Value": "BitMessage"
          },
          {
            "Name": "Message:Type",
            "Value": "Raise"
          }
        ]
      }
    ]
  }

Accessor	Description
Id	Unique Id for each task
Name	A name for the task
Address	Alarm address (pool)
Property MessageMappingFile	The mapping file to load (copy to `.\Config\HumanOS.UHAL.OpcUaControl\`)
Property MessageCount	Amount of messages which are mapped (depends on the Property MessageFormat)
Property StartAddress	The corresponding source address with offset and length (depends on the Property MessageFormat)
Property MessageFormat	BitMessage or Channel32Message
Property Message:Type	Type of each message that occurs from this source

A property which starts with Message: is attached as property to the alarm item (e.g. message) which means additional fields are added with this data and can be used later on.

Mapping means, the alarms and events are defined by the data given and not the data that the alarm source provides.
The mapping source must either be of type JSON and must be structured like this example:

{
  "Messages": [
    {
      "Id": 0,
      "AlarmType": "Alarm",
      "OemId": "Alarm 1",
      "Text": "PU Sammelfehler",
      "Properties": [
        {
          "Name": "MyProperty",
          "Value": "Some other info"
        },
        {
          "Name": "EnableRmq",
          "Value": "1"
        },
        {
          "Name": "EnableRest",
          "Value": "0"
        }
      ]
    }
  ]
}

Accessor	Description
Id	Specifies the bit number (absolute)
AlarmType	Specifies the Alarm type, see Alarm Types in Alarm and Event Source in the Operation manual
OemId	The Condition name of the alarm or event
Text	Specifies the message
Properties	Specify properties which are attached to this alarm or event and can later be accessed
`Properties:Name`	Property name
`Properties:Value`	Property value

Generic Command Access

The command module of OPC-UA server can be accessed using the command info structure.

The command address is made of two node ids. The "@"-sign separates the two ids.
Example: {<object_id>}"@"{<command_id}

Example:

{
  "Id": "D2DFA580-E5C6-4E49-A845-2C9C902899F7",
  "Name": "ReadValue",
  "Type": "CommandNode",
  "Address": "{ns=2;g={ECE37FDF-4862-4543-AF23-48FFDB8203C7}}@{ns=2;g={0012A45C-E9FD-471E-8AD3-8BB85A33B186}}",
  "Arguments": [
    {
      "Name": "Address",
      "DataType": "System.String",
      "Type": "Input"
    },
    {
      "Name": "Value",
      "DataType": "System.String",
      "Type": "Output"
    }
  ]
}

Special Command Access

The OPC-UA control provides following special commands:

opc:WriteData: Writes data to an OPC-UA data node
opc:ReadData: Reads data from an OPC-UA data node

WriteData

opc:WriteData uses following arguments:

Name	Description	Data Type
Address	Address to write data to a data node	System.String
DataType	Data type of the OPC-UA data node	System.String
Value	Value to write	System.String

Example:

{
  "Id": "{30A53102-6737-4A3E-9514-047B938F78A6}",
  "Name": "WriteData",
  "Type": "CommandNode",
  "Address": "opc:WriteData",
  "Arguments": [
    {
      "Name": "Address",
      "DataType": "System.String",
      "Type": "Input"
    },
    {
      "Name": "DataType",
      "DataType": "System.String",
      "Type": "Input"
    },
    {
      "Name": "Value",
      "DataType": "System.String",
      "Type": "Input"
    }
  ]
}

ReadData

opc:ReadData uses following arguments:

Name	Description	Data Type
Address	Address to write data to a data node	System.String

Output argument is:

Name	Description	Data Type
Value	Value from the DataNode	System.String

Example:

{
  "Id": "{48060B81-17B8-477C-9CC9-1B0858465780}",
  "Name": "ReadData",
  "Type": "CommandNode",
  "Address": "opc:ReadData",
  "Arguments": [
    {
      "Name": "Address",
      "DataType": "System.String",
      "Type": "Input"
    },
    {
      "Name": "Value",
      "DataType": "System.String",
      "Type": "Output"
    }
  ]
}

Introduction

Driver Configuration

Device Information

Header​

Example with basic authentication and no secure connection​

Example with store based certificate secure connection​

Data Access​

Special Data Nodes​

Alarm and Event Access​

OEM Message Mapping​

Generic Command Access​

Special Command Access​

WriteData​

ReadData​

Header

Example with basic authentication and no secure connection

Example with store based certificate secure connection

Data Access

Special Data Nodes

Alarm and Event Access

OEM Message Mapping

Generic Command Access

Special Command Access

WriteData

ReadData