OPCUA Plugin

Purpose

The purpose of this plugin is to read data from OPC UA Servers.

Usage

You can run a discover without a configuration file. In this case, all the variables in the OPC UA namespace are displayed in a hierarchical tree format. If the debug is run from the command line with a debug value of -v, the actual values for all the namespace nodes will also be displayed. The returned tree will look something like this:

    Name: Objects.Ardexa.SensorField_15 namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15
        Name: Objects.Ardexa.SensorField_15.WGF34 namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34
            Name: Objects.Ardexa.SensorField_15.WGF34.Ard125 namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34/Ard125
                Name: Objects.Ardexa.SensorField_15.WGF34.Ard125.Ard125.Addr namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34/Ard125.Addr
                Name: Objects.Ardexa.SensorField_15.WGF34.Ard125.Ard125.Rotation_Value namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34/Ard125.Rotation_Value
                Name: Objects.Ardexa.SensorField_15.WGF34.Ard125.Ard125.Power namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34/Ard125.Power
                Name: Objects.Ardexa.SensorField_15.WGF34.Ard125.Ard125.Alarm namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34/Ard125.Alarm
                Name: Objects.Ardexa.SensorField_15.WGF34.Ard125.Ard125.Last_10_Temps namespace_index: 2. NodeID: ns=2;s=Ardexa/SensorField_15/WGF34/Ard125.Last_10_Temps

The namespace index is an integer value to denote the enumerated namespace. It will be listed at the very top of a discovery run. It is also shown in the above listing as ns=2 or namespace_index: 2. In order to log data, there must be a config file. If a configuration file is run with discover, then only those variables in the configuration file and their values will be shown. If using a configuration file YOU MUST specify the correct namespace, since sometimes the same variables names are contained across different namespaces. ALWAYS run discover first to see which variables are available, before developing the config file. The config file defines which variables need to be collected, what names they appear as on the the Ardexa cloud, and the units and scaling. Based on the example above, the configuration file required to collect the last 5 items shown above is as follows. Note that the OPCUA Variable Name is listed as the NodeID (taken from the above listing), but prepended with the namespace index and a colon.

# Ardexa Table Name,    Ardexa Source Name,     Ardexa Variable Name,   OPCUA Variable Name,                                    Type,               Units,      Scale
data,                   machine1,               Address,                2:Ardexa/SensorField_15/WGF34/Ard125.Addr,              keyword,            
data,                   machine1,               Rotation_Value,         2:Ardexa/SensorField_15/WGF34/Ard125.Rotation_Value,    integer,        
data,                   machine1,               Power,                  2:Ardexa/SensorField_15/WGF34/Ard125.Power,             decimal,            W,          0.1
data,                   machine1,               Alarm,                  2:Ardexa/SensorField_15/WGF34/Ard125.Alarm,             bool,               
data,                   machine1,               Temperature,            2:Ardexa/SensorField_15/WGF34/Ard125.Last_10_Temps      array:decimal:3,    C,          10

NOTES:

1. Anything that starts with # is a comment line, and will be ignored

2. The Type can be either: decimal, integer, bool, keyword or array

3. If the Type starts with array, then there must be 3 components separated by a colon :, as follows

   • The 1st item must be the word array

   • The 2nd item must be: decimal, integer, bool, keyword

   • The 3rd item must be an integer, which defines the array index to capture. Indicies start at 1

4. Variables are named as (example) 4:INPUT_3. The leading 4 is the namespace index. The available namespaces are displayed when running a discover.

Authentication is optional. Most OPC UA Servers do not require authentication. If using authentication, a file must be included in the auth_file area which can contain up to 2 items of information as follows (note the uppercase Username/Password):

Username: {whatever}
Password: {whatever}

Also, an OPC UA connection string may have a suffix associated with it. For example, the connection string may be something like: "opc.tcp://192.168.1.10:52345/opcua, where 52345 is the TCP port. The /opcua at the end is a suffix. Include it in the cvonfiguration if one exists, otherwise leave it blank

Using Digital Certificates

Some sites require digital certificates to be submitted to the OPC UA Server. This is very rare. However if you do encounter these sites, you need to generate the public and private key as follows. These certificates MUST be given to the OPCUA Server administrator so they can grant permissions based on these new keys.

git clone https://github.com/FreeOpcUa/python-opcua.git
cd python-opcua/examples
cp generate_certificate.sh ....
nano generate_certificate.sh ....
    organizationName = Ardexa
    -days 3550
chmod 755 generate_certificate.sh
    Country Name (2 letter code) [AU]:AU
    State or Province Name (full name) [Some-State]:ACT
    Locality Name (eg, city) []:Canberra
    Organization Name (eg, company) [Internet Widgits Pty Ltd]:Ardexa
    Organizational Unit Name (eg, section) []:DEV
    Common Name (e.g. server FQDN or YOUR name) []:gc
    Email Address []:[e-mail]

Once this is done, copy the two *.pem files to the directory: /opt/ardexa/config/opcua-ardexa, or use the upload button for the private and public keys. Make sure they are uploaded to the correct name. The OPCUA plugin will change the permission of the private key to 0600 (read only by the root user), if this hasdn't been done already. In addition to creating the digital certificates, you may need to set 2 more arguments. The application URI is a string that is usually needed. This should match the certificate and should be something like: urn:example.org:FreeOpcUa:python-opcua.

The security string details details the crypto algorithms to use, and locations of the public and private keys. It is a comma separate string of 4 items. The last 2 items are the locations of the public and private key, respectively. The security string should be something like: Basic128Rsa15,SignAndEncrypt,/opt/ardexa/config/opcua-ardexa/my_cert.pem,/opt/ardexa/config/opcua-ardexa/my_private_key.pem. You must consult the administrator of the OPC UA server on the exact contents of the security string. BE AWARE OF THE FOLLOWING; in older versions of the plugin, the user had to manually insert the location of the public and private key into the security string. This is no longer required, as the plugin will automatically fill in the security string with the private and public keys, ONLY if they do not already exist.

Certificate Expired

If the following message (or similar) is received, the certificate is most likely expired:

Received an error: MessageAbort(error:StatusCode(BadCertificateTimeInvalid), reason:Certificate has is expired or not yet valid. NotTimeValid: A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file.)

If you are receiving this error when running discovery, check the expiry date to confirm that it has passed using the following command:

openssl x509 -enddate -noout -in my_cert.pem

If it is indeed expired, generate a new certificate using the above process and notify the client that you need them to trust the new certificate.

Arguments

• IP Address .. something like: 192.168.1.4

• configuration File full path ... this is the config file discussed above.

• --port This is an optional entry denoting the TCP Port of the OPC UA server. It is defaulted to 4840

• --namespace_index. This is an optional entry only available when using discover. It is the namespace for which toi discover variables. It is defaulted to 0

• --auth_file ... this is the authentication file discussed above.

• --suffix. This is the suffix, if one exists, as discussed above.

• --app_uri. This is the Application URI, if one exists, as discussed above.

• --security_str. This is the Security String, if one exists, as discussed above.

• --timeout. This is the OPC UA connection timeout. Note that a connection can take longer than the timeout, so long as the initial connection to the OPC UA server is less than the timeout value. The default is 10.0 seconds.

• --report_connection_time. This is a flag (true/false) on whether reporting on OPC UA connection time is required. See below.

• --public_key ... The public key (if being used)

• --private_key ... The public key (if being used)

Debugging OPC UA Connection Time

It is sometimes necessary to measure the speed of connection to the OPC UA server. The report_connection_time will do this. There are 5 broad steps in collecting data from an OPC UA server. These are:

1. Initialise collection program.

2. Connect to the OPC UA Server.

3. Collect data from the OPC UA Server.

4. Close the connection to the OPC UA Server.

5. Format and send data to the Ardexa Cloud.

Once the report_connection_time argument has been selected, the following events will be sent to the data table:

1. Initialsation Event. This will have a source = time_to_initialise, and will show the elapsed time in seconds to undertake task 1 above (Initialise collection program)

2. Connection Event. This will have a source = time_to_connect_to_server, and will show the elapsed time in seconds to undertake task 2 above (Connect to the OPC UA Server)

3. Total Collection Event. This will have a source = total_data_extraction_time, and will show the elapsed time in seconds to undertake tasks 2, 3 and 4 above. That is: a. Connect to the OPC UA Server. b. Collect data from the OPC UA Server. c. Close the connection to the OPC UA Server.

These items will only appear when the log directive is run, and all data is sent to the data table. The filename on which the connection time is requested will also be displayed/collected. Be sure to set the timeout value to JUST BELOW the rate of collection. For example; if the scenario is set to collect data every 30 seconds, then set the timeout to be 29.8. This will result in a log entry being recorded EVERY TIME, even though the connect itself may timeout.