Connecting to the inmation OPC UA Server

This example will show you how to establish a connection to the inmation OPC UA server using an OPC UA client. The first steps involve setting up an instance of the inmation OPC UA Server and creating an endpoint, after that we use the freely available Unified Automation UaExpert client to connect to the server. For more information on the inmation OPC UA Server, please visit the Server Service - UA Server page.

To use the system’s OPC UA Server, the Server service needs to be installed. This can be done using using the Windows Installer, the Node Installer or from the command line.

Creating the OPC UA TCP Server

  1. Go to the Server Model in DataStudio and find the Server Object. If there is no Server object, please follow the instructions on Creating a Server Object.

  2. Right-click the Server object and select Admin  New  OPC UA TCP Server to open the Create Object Wizard.

  3. Enter a name for the OPC UA Server.

  4. Expand the Model Access subsection and enable the checkboxes for the system models which should be exposed by the server. By default, the I/O Model is enabled.

    Access to the I/O Model has to be enabled for the OPC UA Server to expose events.
    Create OPC UA TCP Server Wizard
    Figure 1. Create OPC UA TCP Server Wizard
  5. Click Next to move on to the Communication page of the wizard.

  6. Enter a Listener Port that is not being used by another application or service (default is 4840).

    Create OPC UA TCP Server Wizard - Communication Options
    Figure 2. Create OPC UA TCP Server Wizard - Communication Options
    The Bind to Address and Discovery Path properties are left empty here but can be configured for your particular UA client or system.
  7. Click Create to create the OPC UA TCP Server object in the Server Model.

    Server Model - OPC UA TCP Server Object
    Figure 3. Server Model - OPC UA TCP Server Object

Creating an Endpoint

The OPC UA TCP Server is created however, we need an endpoint to establish a session with an external OPC UA Client. The endpoint specifies the security policy, message security mode and supported user token policies. For this example, we will use the simplest case using no security mode and the Anonymous User Token policy.

  1. Select the OPC UA TCP Server object in the Server Model. Right-click and select Admin  New  OPC UA TCP Server Endpoint to open the Create Object wizard.

  2. Enter a name for the Endpoint object the click Next.

    Create Endpoint Wizard - Common
    Figure 4. Create Endpoint Wizard - Common
  3. In the Communication page of the Create Endpoint wizard, you can enter an Endpoint Path (see note below for more details). However, to keep this example simple we will leave the field blank. Click btn[Next] to go to the User Token Polices page in the Wizard.

    Create Endpoint Wizard - Communication
    Figure 5. Create Endpoint Wizard - Communication
    If the Endpoint Path is entered then this will be appended to the endpoint URL that you use to connect with a UA client. For example, if myendpoint is added as the Endpoint Path property, then the endpoint URL used by the client will be opc.tcp://hostmachine:4840/myendpoint.
  4. On the User Token Policies page, expand the “Anonymous Policy” option and select the “Enable” checkbox. Also, fill out the Profile and Password fields. This maps onto an existing Profile object so please enter the Profile Credentials that will allow access to the system.

    Create Endpoint Wizard - User Token Policies
    Figure 6. Create Endpoint Wizard - User Token Policies
    As mentioned above, the Anonymous Policy can be mapped to any existing Profile in the Access Model (See the Access Model Hands on section for more information on creating profiles and users). The UA Server grants the same permissions to a profile as is defined in the Access model when Object Level Security is set. In this way the Anonymous User Token Policy can be used to restrict access to the namespace when connecting with a UA client.
  5. Click Create to create the Endpoint object in the Server Model tree. The Server Model should look like the example below:

    Server Model Tree  - OPC UA Server and Endpoint
    Figure 7. Server Model Tree - OPC UA Server and Endpoint

Connecting to the system OPC UA Server with a UA Client

Using the configuration set up in the above examples, we can connect to the inmation OPC UA server with an external UA client using an anonymous user token policy and no defined security policy. You can check the connection using your own choice of UA client, however, here a connection will be demonstrated using the Unified Automation UaExpert client.

  1. Open UaExpert and select 'Servers' in the Project panel. Right-click and select Add from the Context Menu to open the Add Server dialog.

    UaExpert - Adding a Server
    Figure 8. UaExpert - Adding a Server
  2. In the Add Server dialog you will find the inmation OPC UA Server in the ServersOnNetwork section.

    UaExpert - Add Server Dialog
    Figure 9. UaExpert - Add Server Dialog
  3. Expand the section and select the Endpoint you created in DataStudio. Hovering above the Endpoint with the mouse will reveal additional information about the Endpoint.

    UaExpert - Selecting the Endpoint
    Figure 10. UaExpert - Selecting the Endpoint
    If the OPC UA client does not detect the server automatically, it also offers an option to enter the URL manually (e.g. in the 'Advanced' tab of UaExpert’s 'Add Server' dialog).
    The URL follows this schema: opc.tcp://<hostname>:<port>/<endpoint>
    The system’s default port for the OPC UA server is 4840 but it can be reconfigured in Listener Port property in the Communication compound of the server object.
  4. Make sure that the "Anonymous" Authentication Settings are selected and click OK to close the Add Server dialog.

  5. In the Project panel, the inmation OPC UA server should now be visible under 'Servers'. Select it, then right-click and select Connect from the context menu.

    UaExpert - Connect to Server
    Figure 11. UaExpert - Connect to Server
  6. The first time you try to connect to the inmation OPC UA Server, the client will inform you that the certificate issued by the server isn’t trusted yet. . Click Trust Server Certificate to add the new certificate to the trusted certificates.

    UaExpert - Untrusted Certificate
    Figure 12. UaExpert - Untrusted Certificate
  7. The client will confirm the addition of the new certificate. Click Continue to close the dialog.

    UaExpert - Confirmation of the New Certificate
    Figure 13. UaExpert - Confirmation of the New Certificate
  8. The inmation OPC UA Server should now be visible in the Project panel, under 'Servers'. Right-click it and select Connect from the Context Menu.

    Connecting to the UA Server
    Figure 14. Connecting to the UA Server
  9. When the connection is established, the Address Space panel reveals the data tree provided by the server. Expand the tree and drag some I/O items to the Data Access panel to see the values updating.

    UaExpert - Connected UA Server with Updating Values
    Figure 15. UaExpert - Connected UA Server with Updating Values

Information Items

When you expand a data item in the Address Space panel, additional information items regarding the Engineering Unit of the data item are provided. Select an information item to display it in UA Expert’s Attributes panel, where the additional information will then be shown in the Value section, as the Value property. By default this Value property is displayed in JSON format.

items additional information

Alternatively, the Value property can be configured to be shown as an individual subsection of the Attributes Panel instead of a JSON string. To do so, go to DataStudio and select the OPC UA TCP Server object in the I/O Model. In the Properties Panel navigate to the Capabilities section and set the checkbox for the Enable Extension Objects property. Once you 'rebrowse' the data tree in UA Expert, the Attributes panel will be updated accordingly.

items additional information resolved

Restricting the Browsable Namespace

The amount of the namespace that is permitted to be browsed depends on the Profile used when setting up the Anonymous User Token policy of the endpoint. Using the system owner "so" profile we can see the entire namespace in all model panels.

  1. Change the profile and password in the Anonymous User Token policy section of the UA Server endpoint to use the Guest Users profile that was created in the Access Model Hands On section.

    Change Anonymous User Token Policy
    Figure 16. Change Anonymous User Token Policy
  2. Click Apply to confirm the changes then return to the UA Expert Client. Disconnect from the Server then reconnect, this time using the Guest Users profile. Browsing the I/O model now only allows access to the section of the namespace that is permitted by the Object Level Security for the Guest Users profile in the Access Model panel.

    Browsing the Namespace using Guest Users Profile Configured as Anonymous User Token Policy
    Figure 17. Browsing the Namespace using Guest Users Profile Configured as Anonymous User Token Policy

Connecting to the OPC UA Server with User Credentials (Profile)

To use Profiles directly as authentication in the UA client you must first enable the User Name Token Policy in the UA Server Endpoint.

  1. To do this, check the box in the Object Properties panel of the endpoint.

    Enable User Name Policy in Endpoint
    Figure 18. Enable User Name Policy in Endpoint
  2. Click Apply to confirm the changes, then switching to the UA Expert client, open the properties for the server and change the Authentication Settings to accept Username and Password. Click OK to confirm changes.

    UA Expert Authentication Settings
    Figure 19. UA Expert Authentication Settings

Now, when you connect to the Server, the User Credentials dialog will appear. Enter a Profile as Username and the correct password to connect.

User Credentials Dialog
Figure 20. User Credentials Dialog

Once connection is achieved, the sections of the namespace that are permitted for that profile can be browsed successfully.

Security Policies and Modes, and Certificate Management

Different security encryption policies can be applied to the system UA Server connections and different security modes utilized. If the server connection is configured to have a security policy then the UA client connecting to it must issue a certificate. The certificate must then be trusted by the system UA server in order for the connection to be successful.

The security policy is configured in the Endpoint object in the Object properties panel of DataStudio. All security policies (except “None”) require a client certificate as well as the server certificate used to connect above.

To change the security policy configuration of your endpoint, …​

  1. select it in the Server Model and open the Communication menu in the Object Properties panel.

  2. Change the Security Mode to 'Sign and Encrypt' and for Security Policy select any other than 'None' from the drop-down list.

    Security Policy and Mode Settings in the Endpoint Object
    Figure 21. Security Policy and Mode Settings in the Endpoint Object
    If you are already connected to the server with a client, any change in the security policy on the server side will disconnect the client. Security settings on the client side and on the server side have to match to reestablish the connection automatically.
  3. In the UaExpert Client, open the Server properties connection properties and change the Security Policy and Message Security Mode fields to match those configured for the Endpoint in the previous step (you can use Anonymous or User Name policy). Then click OK to close the dialog.

    UaExpert - Server Settings
    Figure 22. UaExpert - Server Settings
  4. Try to connect to the server in UaExpert. You will receive the error that "Connecting failed with error 'BadSecurityChecksFailed'". The connection fails because the UaExpert client self-signed certificate is rejected by the system UA server. This is because the system UA server is configured to reject all client certificates.
    To change this configuration, …​

  5. select the UA Server object in the Server Model of DataStudio and open up the Certificate Management menu.

    Certificate Management Options
    Figure 23. Certificate Management Options

    The certificate management syncs with the certificates store (found in the 'inmation.root\certificates' directory) and displays the trusted and rejected certificates from the store. The rejected certificate from the failed UaExpert connection is displayed and can be found in the 'inmation.root\certificates\rejected' directory.

    A record of the rejected certificate is also entered into the system log. Open a log display (right click on the UA server object and select Admin > Open Log > last 30 mins) and double click on the information entry to view details of the rejected certificate. All rejected certificates can be evaluated before allowing connection.
  6. To trust the UaExpert Client certificate, select 'Trust' from the Trust Mode drop-down list in the Certificate Management settings and click Apply. For more information about the Trust Modes, see Trust Mode Options.

    Certificate Management - Trust Mode
    Figure 24. Certificate Management - Trust Mode
  7. Now, try to connect to the system server in the UaExpert client. The first connection attempt will fail but the UaExpert client certificate will be moved to the trusted certificates directory of the local certificate store (inmation.root > certificates > certs).

    UaExpert certificate moved to "trusted"
    Figure 25. UaExpert certificate moved to "trusted"
  8. Try again to connect to the server with UaExpert. This time the connection will be successful and you can browse the server namespace using UaExpert. The Trust Mode of the system UA server can be returned to Reject to prevent any other client certificates being accepted.

    Rejected certificates can also be manually moved from the "rejected" folder to the "certs" folder in the certificate store. Upon re-connection with a client, the connection will be successful.

Subscribing to Events

To subscribe to events with the UA Client it is first necessary to create an event object in the system. For this example, …​

  1. create an Event Stream below an OPC UA Datasource in the I/O Model.

    The Unified Automation ANSI C simulation server can generate sample events by writing "True" or "False" to the Trigger_SampleEvent boolean IO-item located in the Demo  004_Events IO Node.
  2. Create an Event Stream below an OPC UA Datasource and name the object "ESUA".

    Event Stream - OPC UA Server
    Figure 26. Event Stream - OPC UA Server
  3. Connect to the inmation OPC UA server with an external client as described above (for this example we will use UA Expert).

  4. In UA Expert, open an "Event View" by clicking on Document  Add…​ in the toolbar menu and choosing "Event View" from the Document Type drop-down menu. Click Add.

  5. In the address space panel of UA Expert, navigate in the I/O Model namespace (Root > Objects > Root) to the node which represents the OPC UA ANSI C Datasource and expand. The "ESUA" object created in step 1 should be visible as a node.

    Browse I/O Model namespace
    Figure 27. Browse I/O Model namespace
  6. Drag and drop the "ESUA" node into the "Configuration" pane of the "Event View" document that you opened. It can take up to 30 seconds for the addition to complete so be patient. Events should begin to appear in the "Events" pane

    Event subscription
    Figure 28. Event subscription
  7. Once added, the client will have successfully have subscribed to events from that node. If you do not see any events in the "Events" pane of the Event View document, trigger an event on the server side (see note at beginning of section).

  8. Click on an Event in the "Events" pane and look at the details in the "Details" panel.
    The majority of the BaseEventType properties are not filled, only EventId, EventType and time-related properties. Server/Object identifies the node which emitted the event. The value of EventType is always the nodeID of "ForwardedEventType" which is a sub-type of the standard "BaseEventType" and used to represent all events forwarded from the core to the server. The "Identifier" points to the Event Type as it is represented in the Server Model hierarchy.

    Event Details
    Figure 29. Event Details
  9. In the "Configuration" pane, the Server/Object node for the added "ESUA" object can be expanded and the "ForwardedEventType" can be found under the "SimpleEvents". In the default state, the "ForwardedEventType" has only one property, RawEventContent that contains the whole event information according to the Event Document Schema. Custom Event Type Properties can be added in the Server Model to map fields in the Event Document Schema. Any custom properties added will be visible under the "ForwardedEventType" in the "Configuration" pane.

    Event Type Configuration
    Figure 30. Event Type Configuration

Subscribing to all Events

It is also possible to subscribe to all events from the server by adding the standard "Server" node by drag and drop to the "Event View" document "Configuration" pane.

Subscribe to Server Node
Figure 31. Subscribe to Server Node
Only events from event sources visible in the address space will be forwarded to the client in this subscription.
It is possible to modify this subscription in the "Configuration" pane by selecting only certain event types (for example "ForwardedEventType") and clicking Apply.

Adding Custom Event Type Properties

Custom Event Type Properties can be added in the Server Model under the "ForwardedEventType" object. The purpose of this is to automatically map properties to fields in the Event Document Schema to make certain event properties immediately visible in the client.

For this example we will use the "ESUA" object created in the previous section as our subscription object to map properties to fields

  1. Create two Event Type Properties under the "ForwardedEventType" object in the Server model with the following properties configured:

    Table 1. Event Type Property - Property configuration
    Object Name Event Type Property Mapping

    Severity

    e_.u_.2041.2051.d_

    SourceName

    e_.u_.2041.2045.d_

    Event Type Properties in Server Model
    Figure 32. Event Type Properties in Server Model
    The mapping "dot" paths configured here correspond to the OPC UA section of the Event Document Schema. The "2041" refers to the nodeID of the BaseEventType node and the following numbers to the nodeIDs of the corresponding property references.
  2. Open a new "Event View" document in UA Expert and add the "ESUA" node to the "Configuration" pane to subscribe to the events. Wait for some events to come in, then click on one in the "Events" pane and look at the "Details".

    Added Event Type Properties - UA Expert
    Figure 33. Added Event Type Properties - UA Expert
  3. In the "Events" pane, the Severity and SourceName columns are now populated with values mapped directly from the RawEventContent property. The Severity and SourceName now also appear as properties with associated values in the "Details" pane.

  4. Go to the "Configuration" pane of the "Event View" document and expand the SimpleEvents node and subsequently the ForwardedEventType node. Although the Event Type Properties we created were added to the ForwardedEventType node they do not appear under that node in the "Configuration" window. This is because the Object Names we configured exactly match the names of BaseEventType properties. Therefore they are directly associated with these properties.

    Event Type Configuration
    Figure 34. Event Type Configuration
  5. Now create a new Event Type Property in the Server Model with the following configuration:

    Table 2. New Event Type Property - Property configuration
    Object Name Event Type Property Mapping

    P2

    e_.u_.2041.2050.d_

    This mapping to the nodeID "2050" is the OPC UA Message field of the Event Document Schema.

  6. Open a new "Event View" document in UA Expert and add the "ESUA" node to the "Configuration" pane to subscribe to the events. Expand the SimpleEvents node and subsequently the ForwardedEventType node. This time the P2 Event Type Property is visible under the ForwardedEventType node as the Object Name does not match any of the BaseEventType property references.

    P2 property under ForwardedEventType node
    Figure 35. P2 property under ForwardedEventType node
  7. Select an event in the "Events" pane of the "Event View" document and look at the details in the "Details" pane. The P2 property is visible and the value is successfully mapped to the Message field of the OPC UA event in the RawEventContent.

    P2 property value in Event Details
    Figure 36. P2 property value in Event Details