OPC-UA Data Model Configuration

The OPC-UA server allows to serve different data models for a client. There are two types of models:

• Default model; is automatically generated by HumanOS based on the structure in the device config file
• UaModels; can be created and generated with Unified automation's UaModeler, links to this models must be specified as properties in the device config file

The configuration in settings.json contains a list of models. Each Model that is to be loaded must be configured in this list. When no model is specified into the list, the OPC-UA plugin creates itself a default model configuration.

UaModels requires a special model configuration (Output of UaModeler). The generated UaModels must be placed as xml files into the folder .\Config\HumanOS.PeSeL.OPCUAServer\. With the HumanOS IoT Designer, the modelling files can be added to the OpcUa plugin by right-clicking as shown in the image below.

Properties of a model config

Name	Description	Data Type
Name	Name of the model. This name is also used in the device configuration properties to map the data nodes. Use 'Default' for the default model and any custom name for a custom model.	System.String
DeviceFilter	[opt] Filter to specify the devices which are enabled for this model	System.String
RootBrowseName	[dm*][opt] Specifies the root browse name, default RootBrowse name is HumanOS	System.String
EnableConfigDataCommand	[dm*][opt] Flag to enable the config data command (Activates a command node on Opc-Ua server to get the opcua config data)	System.Boolean
DeviceModelNodeId	[cm*] NodeId from the UaModel, which corresponds to the HumanOS device node.	System.String
ModelUri	[cm*] ModelUri from the UaModel, which corresponds to the HumanOS device node.	System.String

dm* = Property only available for the default model
cm* = Property only available for a custom model

Example of a default model configuration

"Models": [
  {
    "Name": "Default",
    "RootBrowseName": "ProjectXYZ",
    "DeviceFilter": "node.hasProperty<bool>(\"EnableDefault\", true)",
    "EnableConfigDataCommand": true
  }
]

Explanation of the DeviceFilter

The device filter uses a specific expression to check a property of a device. Based on the return value from the expression, the model for the corresponding device is instantiated or not.

Example:

node.hasProperty<bool>("EnableDefault", true)

In the example, node corresponds to the device node. The hasProperty<bool>("EnableDefault", true) method is used to check whether a property with the name EnableDefault and data type bool is present and true in the device node or not. If the property is present and true, the device is instantiated for the model.

If no filter is specified, the model is instantiated for each device.

Explanation of the DeviceModelNodeId and ModelUri

The properties DeviceModelNodeId and ModelUri are used to configure the link from the model configuration (HumanOS) to the UaModel (in XML file format) template node. These properties must match the configured values in the UaModeler exactly so that the model can be loaded.

The figure below shows the UaModeler with the umati example MachineTool_brownfield. In this example, an instance of the MachineTool_brownfield node is to be created for each HumanOS device. To do this, this node is selected and the property namespace (blue) must be entered in the model configuration under ModelUri. But without NamespaceIndex. The property NodeId must be entered in the format i=5004 in the model configuration under DeviceModelNodeId.

Example of the configuration

"Models": [
  {
    "Name": "umati",
    "ModelUri": "http://umati.org/UA/1.4/brownfield/",
    "DeviceModelNodeId": "i=5004",
    "DeviceFilter": "node.hasProperty<bool>(\"EnableUmati\", true)"
  }
]

Functionality:

1. The UaModel template node is loaded into the server first.
2. Then, for each device that is loaded for this model, a copy of the UaModel template node including all sub-nodes is created and linked to the device.
3. The device name from the model is replaced by the HumanOS name in Device.json
4. The data nodes in Device.json are mapped to the device using the mapping properties. If a node cannot be mapped, HumanOS issues an error message. Loading the model for this device is not canceled.

Configuration examples

Simple Configuration

{
  "Disabled": false,
  "UaServer": {
    "Id": "3B3421CB-92E5-4D51-B172-33A180F21824",
    "Name": "HumanOS OPC-UA Server",
    "Port": 4840,
    "ServerUri": "urn:localhost:HumanOS:OpcUaServer",
    "ServiceRule": {
      "BindingRuleId": "128A39CA-F82B-4662-A246-7C9A490CD7BD",
      "UnbindingRuleId": "55458C10-C21F-47DB-BB32-31A90D4D8C97",
      "Type": "All"
    }
  }
}

Extended Configuration

{
  "Disabled": false,
  "UaServer": {
    "Id": "3B3421CB-92E5-4D51-B172-33A180F21824",
    "Name": "HumanOS OPC-UA Server",
    "Port": 4840,
    "ServerUri": "urn:localhost:HumanOS:OpcUaServer",
    "CertificatePath": "$(AppConfig:CertificatePath)OpcUaCertificateStores",
    "DisableAnonymous": true,
    "DisableBasicNoSecurity": true,
    "ServiceRule": {
      "BindingRuleId": "128A39CA-F82B-4662-A246-7C9A490CD7BD",
      "UnbindingRuleId": "55458C10-C21F-47DB-BB32-31A90D4D8C97",
      "Type": "All"
    },
    "Models": [
      {
        "Name": "Default",
        "RootBrowseName": "ProjectXYZ"
      },
      {
        "Name": "umati",
        "ModelUri": "http://yourorganisation.org/MachineTool-Example/",
        "DeviceModelNodeId": "i=5002",
        "DeviceFilter": "node.hasProperty<bool>(\"EnableUmati\", true)"
      }
    ]
  }
}

Windows store Configuration

{
  "Disabled": false,
  "UaServer": {
    "Id": "3B3421CB-92E5-4D51-B172-33A180F21824",
    "Name": "HumanOS OPC-UA Server",
    "Port": 4840,
    "ServerUri": "urn:localhost:HumanOS:MyServer",
    "CertificatePath": "LocalMachine\\My",
    "CertificateTrustedPath": "LocalMachine\\Trust",
    "CertificateIssuerPath": "LocalMachine\\Root",
    "CertificateRejectedPath": "LocalMachine\\Disallowed",
    "CertificateSubject": "CN=MyServer/O=myorg/DC=myhost",
    "DisableAnonymous": false,
    "DisableBasicNoSecurity": true,
    "StoreType": "Windows",
    "ServiceRule": {
      "BindingRuleId": "128A39CA-F82B-4662-A246-7C9A490CD7BD",
      "UnbindingRuleId": "55458C10-C21F-47DB-BB32-31A90D4D8C97",
      "Type": "All"
    }
  }
}

Default Model

The server structure maps the different devices of a HumanOS® runtime, each one as a separate OPC-UA object node.
Below the device, the internal structure is mapped, such as groups, data nodes and commands:

• Device A
  • Data nodes and commands
  • Groups
    • Data node and commands
• Device B
  • Data nodes and commands
  • Groups
    • Data nodes and commands

Customize the Default node model

In HumanOS®, node Ids are always GUIDs to avoid data collision between different machines and devices. The default behavior is to use this Id also for OPC-UA node id. This only applies to the default data model.

Property	Description	Data Type
Id	Id of data node is mapped directly to NodeId of OPC-UA	System.Guid
Name	Name is mapped to DisplayName	System.String

However, each data node can overwrite this behavior by adding specific properties. The following properties can be added to any DataNode, ConstantNode or GroupNode.

Property	Description	Data Type
opc-ua:Ignore	[opt] Ignore the data node and sub nodes for the default model.	System.Boolean
opc-ua:NodeId	[opt] Overwrites the id of the node.	System.String
opc-ua:DisplayName	[opt] Overwrites the name of the node.	System.String
opc-ua:TypeDefinition	[opt] Overwrites the type definition of the node. This property only has an effect for data nodes (Specify 'PropertyType' for a Property; for possible values see UnifiedAutomation.UaBase.VariableTypeIds)	System.String
opc-ua:Namespace	*[opt] Overwrites the namespace of the device. Default Namespace URI is http://www.humanos.ch/OPC-UA/Instances	System.String

* The property is only available on the root device node.

Example:

{
  "Id": "95C03595-6408-4ADD-A927-96A50C4D2598",
  "Name": "RunningState",
  "DataType": "System.Int32",
  "DataClass": "Event", 
  "Value": 1001,
  "Unit":  "km",
  "HistoryMode": {
    "Retention": 20,
    "SamplingRate": 2000
  },
  "Properties": [
    {
      "Name": "opc-ua:NodeId", 
      "Value": "MachineA:RunningState"
    }, 
    {
      "Name": "opc-ua:DisplayName", 
      "Value": "Running Status"
    }
  ]
}

Customize the custom node model

In chapter Explanation of the DeviceModelNodeId and ModelUri is explained, how to link a template node of a custom model with the model config.

Each node in a device can now be linked anywhere in the customer-specific UaModel. The interface between the custom opc-ua data model and the device data model is specified with properties at the data node. The link between the data node and the custom model is set with the property type mapping. A simple conversion of a value can be performed with the property type values. If a generic OpcUa model is to be used for multiple devices, unsuitable nodes can be removed from the generic model for the device using the IgnoredNodes property. The following table shows the available properties for the HumanOS Nodes.

Property	Description	Data Type
opc-ua:$(ModelName):Mapping	Defines the mapping into the custom data model. Mandatory for working with custom data models.	System.String
opc-ua:$(ModelName):Values	[opt] Value mapping. Each mapping must be separated with ";". The wildcard "" indicates "any value". Example: 1=VALUE1;2=Value2;=Value3.	System.String
opc-ua:$(ModelName):NodeId	*[opt] Overwrites the id of the node. This property only has an effect on the custom model and is only available for the root device node. All other node id's must be configured directly in the custom model	System.String
opc-ua:$(ModelName):Namespace	*[opt] Overwrites the namespace of the device. CAUTION: Be careful with duplicate NodeId's in the same namespace. This can cause problems.	System.String
opc-ua:$(ModelName):IgnoredNodes	*[opt] Specifies which nodes should be hidden from the custom data model. The value is a mapping array, delimited with new line character '\n'.	System.String[]

* The property is only available on the root device node.

Explanation of the Mapping property

The name of the mapping property consists of opc-ua:$(ModelName):Mapping, where $(ModelName) corresponds to the name of the model in the model configuration.
For example, we have the following model config:

"Models": [
  {
    "Name": "umati",
    "ModelUri": "http://umati.org/UA/1.4/brownfield/",
    "DeviceModelNodeId": "i=5004",
  }
]

The mapping property name must be opc-ua:umati:Mapping.

The mapping property value must contain the path to the node in the template model, starting from the root template node.
For example, we have the following model whth the root template node MachineTool_brownfield:

If a data node is to be associated with the ChannelMode, the value of the mapping property must be Monitoring/Channel1/ChannelMode.

For the sake of completeness, an example data node in Device.json is shown below:

{
  "Id": "95C03595-6408-4ADD-A927-96A50C4D2598",
  "Name": "ChannelMode",
  "DataType": "System.Int32",
  "DataClass": "Event", 
  "Value": 2,
  "Properties": [
    {
      "Name": "opc-ua:umati:Mapping", 
      "Value": "Monitoring/Channel1/ChanelMode"
    }
  ]
}

Explanation of the Values property

The name of the values property consists of opc-ua:$(ModelName):Values, where $(ModelName) corresponds to the name of the model in the model configuration.
For example, we have the following model config:

"Models": [
  {
    "Name": "umati",
    "ModelUri": "http://umati.org/UA/1.4/brownfield/",
    "DeviceModelNodeId": "i=5004",
  }
]

The values property name must be opc-ua:umati:Values.

The values property value must contain a semicolon separated list of value mappings in the format $(RawValue)=$(OpcUaValue).
The character * maps all values. For example, we have the following states in the source node (0 = Off, 1 = Startup, 2 = Running), which should be mapped to Opc-Ua states (0 = Off, 1 = On, 2 = Other). Then the value of the values property must be 0=0;2=1;*=2.

Below is the example data node with the value mapping of this sample.

{
  "Id": "95C03595-6408-4ADD-A927-96A50C4D2598",
  "Name": "MachineState",
  "DataType": "System.Int32",
  "DataClass": "Event", 
  "Value": 2,
  "Properties": [
    {
      "Name": "opc-ua:umati:Mapping", 
      "Value": "Example/MyCustomNode"
    },
    {
      "Name": "opc-ua:umati:Values", 
      "Value": "0=0;2=1;*=2"
    }
  ]
}

Explanation of the IgnoredNodes property

The name of the IgnoredNodes property consists of opc-ua:$(ModelName):IgnoredNodes, where $(ModelName) corresponds to the name of the model in the model configuration.

The IgnoredNodes property value must contain a new line separated list of mappings like the value of the mapping property.

For example, we want to remove the nodes 'MachineTool_brownfield/Monitoring/Spindle1' and 'MachineTool_brownfield/Monitoring/Stacklight' in the figure below.

Then the value of the IgnoredNodes property must be Monitoring/Spindle1\nMonitoring/Stacklight.

Below is the example device node with the IgnoredNodes property of this sample.

{
  "Id": "{6826dfc1-e9d1-48b8-95dd-b574251e5f2d}",
  "Name": "TestDevice",
  "DriverId": "effd2b2f-89b0-4d38-bac5-e6bfc3ea7498", //never change
  "Address": "29575400",
  "Properties": [
    {
      "Name": "EnableUmati",
      "Value": true
    },
    {
      "Name": "opc-ua:umati:IgnoredNodes",
      "DataType": "System.String[]",
      "Value": "Monitoring/Spindle1\nMonitoring/Stacklight"
    }
  ]
}

INFORMATION

UAModel Nodes that exist due to a modelling rule cannot be ignored.