How to connect a machine with the OPC UA Connector?

1. Before you begin

The OPC UA Connector will connect your machines to innius for real-time data processing and monitoring. The OPC UA Connector is contained in a zip package along with some default configuration files and a self-signed certificate. Download the zip (Windows 10) appropriate for your system and extract the zipfile to a folder of your choice. If there is no version of the OPC UA Connector for your environment please contact support.

Note: if you are using a Linux environment it might be necessary to install some dependencies depending on your version. Please refer to https://www.microsoft.com/net/core#linuxubuntu for instructions on what to download. It is not necessary to install dotnet core itself.

 

2. Configuration

The innius OPC UA Connector has two configuration files: a security configuration and a subscription configuration. The first is optional and allows you to change the certificate that is used by the application to communicate with the OPC UA server. The subscription configuration is required as it contains the information on which machines and sensors should be connected to innius. Both of these are located in the “config” folder. Furthermore, both configuration files are in JSON format. The JSON format is explained in Chapter 2.1, using the configuration files needed for the innius OPC UA Connector as an example. If you are already familiar with JSON feel free to skip ahead to Chapter 2.2.

2.1 The JSON format

JSONs consist of key-value pairs, wrapped in brackets and separated by commas. The values can be numbers, strings (a word or sentence wrapped in quotes) or other sets of key-value pairs wrapped in brackets. Looking at Figure 1 we see an example of such a JSON. The meaning of what is written there will be explained in Chapter 2.3. For now we focus on the JSON itself, which is the structure of the document.

Figure 1: An example of the JSON format.

The numbers in figure 1 denote important elements within the JSON.

  1. The top element in the JSON. Everything within these two brackets is part of the configuration.
  2. The key of a json key-value pair. This indicates what the value corresponds to. In this case the key is “nodeid”, which tells the innius OPC UA Connector that the following value will be the node id in OPC UA of that particular sensor. The key is followed by a colon and after that its value.
  3. The value of a key. Followed by a comma if more key-value pairs are present after this value. In this case a string but it could well be a number or another JSON element.
  4. A JSON element. It is possible to define smaller boxes of key-value pairs within the all-encompassing box. This particular example highlights the configuration of a sensor.
  5. Square brackets denote the value is an array of things, in this case an array of machines. This allows you to place many machines within these square brackets, where each machine has its own JSON element. The same is done for sensors, which is a key within the machine element, as a machine can have many sensors.

 To validate whether or not your custom configuration is valid there are many online validators you can use, for example https://jsonformatter.curiousconcept.com/.

2.2 Security certificate

Ensure that the OPC UA Server accepts the innius security certificate. By default the application will use a self-signed certificate located in the “Certificates/Application” folder. The default security configuration has the keys as depicted in Figure 2. If you wish to use a different certificate it can be done by specifying it in the securityConfiguration file.

name
data type
description
expected values
comments
applicationName string the name of the application in the certificate optional The default is "innius"
applicationUri string the URI of the application in the certificate optional The default is "urn:toincrease:innius:inniusOPC"
subjectName string the subject name in the certificate optional The default is "CN=applicationName,DC=To-Increase"
applicationCertificates

CertificateStore

object

Indicates where the certificate for the application can be found. optional Defaults to <innius installation directory>/Certificates/Applications
trustedCertificates CertificateStore

object

 Indicates where the certificates for trusted applications, like the OPC UA server, can be found. optional Defaults to <innius installation directory>/Certificates/UA Applications
trustedAuthorities

CertificateStore

object

Indicates where the certificates of trusted certificate authorities can be found. optional Defaults to <innius installation directory>/Certificates/UA Certificate Authorities

 

Here the Certificate store object is defined as follows: 

name
data type
description
expected values
comment
StoreType string The type of certificate store "Directory"  
StorePath string The path to the certificate store.   Should always be in a subfolder of the innius installation folder.

 

The application will always look for the security configuration in the config folder with the name “securityConfiguration”. If you make a new file rather than editing the existing one ensure that this is the case.

Figure 2: The default security configuration.

2.3 Subscription Configuration

By default the program will use the subscription configuration located in the config folder. To get the configuration you need you can alter this file or refer to another configuration file when running the program (see Chapter 3 for the details) or use the export button on the sensors overview page as described in section 2.3.1. The default configuration shown in Figure 3 connects the sample OPC UA Server to the innius cloud. The subscriptionConfig is roughly divided in three parts: the general part, the machines and the sensors of those machines.

General:

name
data type
description
expected values
comments
maxPublishingInterval integer The maximum amount of time in milliseconds the events from OPC UA are gathered before they are send to innius. Optional The default is 1 minute.
maxBufferedMessages integer

Determines how many messages are gathered prior to sending the data to innius.

Optional The default is 100.
opc_url string The url of the OPC UA Server that the innius OPC UA client will connect to.    
machines

array of machine

objects

A list of the machines that will be connected to innius.    

 

Setting the maxPublishingInterval and maxBufferedMessages values low will make for faster delivery if you have only a few sensors (if the maximum isn’t reached in about a second) but it will also increase the network traffic so choose these values based on your needs. 

Figure 3: The default subscription configuration.

Machine:

name
data type
description
comments
nodeid string The id of the node representing the machine within the OPC UA server.  
inniusId string The id of the machine within innius. This is provided when connecting the machine on the website. Click here for more details.
apikey string Key to validate that the machine may send data to innius.

This is provided when connecting the machine on the website. Click here for more details.

sensors

array of

sensor objects

A list of the sensors of this machine that will be connected to innius.  

 

Sensors:

name
data type
description
expected value
comments
nodeid string

The id of the node representing the output of the sensor within the OPC UA server.

This node will be subscribed to and have its data send to innius.

   
sensorid string The sensor name as defined when creating the sensor in innius.    
publishInterval integer The interval at which data is obtained from the server in seconds. optional The default is once every second
position integer When provided the innius OPC UA client assumes the sensor is part of a compound sensor at the provided position. optional  

2.3.1. Export OPC UA Configuration

If you browse to the sensor overview on the innius webpage you will see a button called "Export OPC UA Configuration" (see Figure 4). Clicking this button will create an OPC UA subscription configuration based on the physical sensors you have defined in innius. Replace the configuration file in the config folder with the one you just downloaded, optionally change some parameters, and proceed to chapter 3.


3. Execution

The innius OPC UA Connector comes in two flavors that vary in how they are executed. The first option is the Windows service. The second is the command line application.

3.1 Windows Service

If you have a windows version of the application it will most likely be this variant. It can be run regularly from the command line[i] to test the configuration. This will use the current directory's config folder for the configuration files.

To install the OPC UA Connector as a service, you need to run a command prompt as administrator. Then perform the following steps:

  1. In the command prompt go to the innius folder. In the example below the innius files are in C:\Program Files\innius 
  2. Type in the name of the Connector + .exe followed by “install”.

  3. You will then be prompted for the path to the config file. If you enter nothing it will assume it is in the config folder with the name “subscriptionConfig.json”. Altering this file will not result in an update to the configuration. To do this the service needs to be restarted.

  4. First the config file will be validated. The certificates and config files are then copied to C:\ProgramData\innius which will be the working directory for the service. Any logging will also end up here.

  5. After that restart the computer or start the service by opening the services menu (search for "services" on your system), search for "innius OPC UA" and start it.  The service is configured to automatically start when the computer starts and to automatically restart when it fails.

Uninstalling the service works in a similar fashion to installing it, except the command is “uninstall” instead of “install”.

3.2 Command Line application

All Linux variants are command line applications that allows for some parts of the configuration to be done on the command line. These parts of the configuration and their corresponding command line arguments are:

  • -c : changes the path to the subscription configuration                
  • -ou: changes the url of the opc server
  • -mbm: changes the maximum amount of buffered messages
  • -mbi: changes the maximum amount of time between sending data to innius
Have more questions? Submit a request

Comments