OPC UA

Overview¶

OPC Unified Architecture (OPC UA) is a communication protocol for industrial automation developed by the OPC Foundation. OPCUA is based on client-server communication.

Kelvin Opcua Client Bridge APP application works as a client, pulling data from the server's address space.

OPCUA has a lots of concepts that can be consulted online here. However, to use the kelvin-bridge-opcua-client application these are the most important of having knowledge of:

Prerequisite:

Complete the Getting Started Guide

Retrieving the application¶

The application should be available on your platform's Application Registry. We can search the application registry with the command:

kelvin appregistry search opcua

[kelvin.sdk][2021-07-08 19:30:47][I] Searching applications that match "opcua"
[kelvin.sdk][2021-07-08 19:30:49][I] 
*************************** Applications ***************************
+----------------------------+----------------------------+--------+------------------+----------------------------------+
| Name                       | Title                      | Type   | Latest Version   | Updated                          |
|----------------------------+----------------------------+--------+------------------+----------------------------------|
| kelvin-bridge-opcua-client | kelvin-bridge-opcua-client | bridge | 1.0.4            | 2021-07-01 21:45:58.116754+00:00 |
| kelvin-opcua-demo-server   | kelvin-opcua-demo-server   | docker | 1.0.3            | 2021-06-30 20:06:28.970002+00:00 |
+----------------------------+----------------------------+--------+------------------+----------------------------------+

In this case, we will be using the application named kelvin-bridge-opcua-client and the latest version is 1.0.4.

Note

Use the app version found in your app registry list.

kelvin appregistry download kelvin-bridge-opcua-client:1.0.4

[kelvin.sdk][2021-07-08 19:34:37][I] Downloading application "kelvin-bridge-opcua-client:1.0.4"
[kelvin.sdk][2021-07-08 19:34:42][R] Successfully logged on registry "alpha.kelvininc.com:5000"
[kelvin.sdk][2021-07-08 19:34:42][I] Pulling "kelvin-bridge-opcua-client:1.0.4" from "alpha.kelvininc.com"
[...]                                                                                                                                               
[kelvin.sdk][2021-07-08 19:35:04][R] Successfully pulled "kelvin-bridge-opcua-client:1.0.4" from "alpha.kelvininc.com"
[kelvin.sdk][2021-07-08 19:35:04][R] Application "kelvin-bridge-opcua-client:1.0.4" successfully downloaded to the local registry
[kelvin.sdk][2021-07-08 19:35:04][R] Use `kelvin app images unpack` to extract its contents

Emulating kelvin-bridge-opcua-client¶

Start by downloading the demo opcua server and starting it:

> kelvin appregistry search opcua-demo
[kelvin.sdk][2021-07-08 20:14:35][I] Searching applications that match "opcua-demo"
[kelvin.sdk][2021-07-08 20:14:37][I] 
*************************** Applications ***************************
+--------------------------+--------------------------+--------+------------------+----------------------------------+
| Name                     | Title                    | Type   | Latest Version   | Updated                          |
|--------------------------+--------------------------+--------+------------------+----------------------------------|
| kelvin-opcua-demo-server | kelvin-opcua-demo-server | docker | 1.0.3            | 2021-06-30 20:06:28.970002+00:00 |
+--------------------------+--------------------------+--------+------------------+----------------------------------+

> kelvin appregistry download kelvin-opcua-demo-server:1.0.3
[kelvin.sdk][2021-07-08 20:15:52][I] Downloading application "kelvin-opcua-demo-server:1.0.3"
[kelvin.sdk][2021-07-08 20:15:57][R] Successfully logged on registry "alpha.kelvininc.com:5000"
[kelvin.sdk][2021-07-08 20:15:57][I] Pulling "kelvin-opcua-demo-server:1.0.3" from "alpha.kelvininc.com"
 [...]
[kelvin.sdk][2021-07-08 20:16:02][R] Successfully pulled "kelvin-opcua-demo-server:1.0.3" from "alpha.kelvininc.com"
[kelvin.sdk][2021-07-08 20:16:02][R] Application "kelvin-opcua-demo-server:1.0.3" successfully downloaded to the local registry
[kelvin.sdk][2021-07-08 20:16:02][R] Use `kelvin app images unpack` to extract its contents

Warning

Remember to use the app version in your app registry

Note

Because we downloaded the application from a registry, the image was tagged with its environment. For now, we'll use docker to untagg it, so the emulation process is easier:

docker tag alpha.kelvininc.com:5000/kelvin-opcua-demo-server:1.0.3 kelvin-opcua-demo-server:1.0.3

Download this demo server sample configuration and start the opcua demo server with it:

> kelvin emulation start --app-config opcua_demo_server_config.yaml kelvin-opcua-demo-server:1.0.3
[kelvin.sdk][2021-07-08 21:14:42][R] Attempting to launch application "kelvin-opcua-demo-server:1.0.3" on the emulation system
[kelvin.sdk][2021-07-08 21:14:42][R] Emulation configuration loaded from: "/home/joao/workspace/flight/control-frame/opcua-app/opcua_demo_server_config.yaml"
[kelvin.sdk][2021-07-08 21:14:43][I] Valid schema available locally. Using cached version (/home/joao/.config/kelvin/schemas/2.0.0.json)
[kelvin.sdk][2021-07-08 21:14:45][R] Kelvin Emulation System is online
[kelvin.sdk][2021-07-08 21:14:45][I] Loading configuration and starting the application "kelvin-opcua-demo-server:1.0.3"
[kelvin.sdk][2021-07-08 21:14:45][I] Valid schema available locally. Using cached version (/home/joao/.config/kelvin/schemas/2.0.0.json)
[kelvin.sdk][2021-07-08 21:14:47][R] 
    Emulation configurations applied to container:
        └── Environment variables:
           - Loading "OPCUA_SERVER_CONFIG_FILE" from the configuration file
        └── Ports:
           - Container port "48010" connected to host port "48010"
[kelvin.sdk][2021-07-08 21:14:47][R] Application successfully launched: "kelvin-opcua-demo-server:1.0.3"

Note

Remember to update the alpha registry with the environment you're logged in

Note

Because we downloaded the application from a registry, the image was tagged with its environment. For now, we'll use docker to untag it, so the emulation process is easier:

docker tag alpha.kelvininc.com:5000/kelvin-bridge-opcua-client:1.0.4 kelvin-bridge-opcua-client:1.0.4

Download this opcua client sample config and start the opcua demo server with it:

> kelvin emulation start --app-config opcua_client_config.yaml kelvin-bridge-opcua-client:1.0.4 --show-logs
[kelvin.sdk][2021-07-08 21:58:14][R] Attempting to launch application "kelvin-bridge-opcua-client:1.0.4" on the emulation system
[kelvin.sdk][2021-07-08 21:58:14][R] Emulation configuration loaded from: "/home/joao/workspace/flight/control-frame/opcua-app/opcua_client_config.yaml"
[kelvin.sdk][2021-07-08 21:58:16][I] Valid schema available locally. Using cached version (/home/joao/.config/kelvin/schemas/2.0.0.json)
[kelvin.sdk][2021-07-08 21:58:19][R] Kelvin Emulation System is online
[kelvin.sdk][2021-07-08 21:58:19][I] Loading configuration and starting the application "kelvin-bridge-opcua-client:1.0.4"
[kelvin.sdk][2021-07-08 21:58:19][I] Valid schema available locally. Using cached version (/home/joao/.config/kelvin/schemas/2.0.0.json)
[kelvin.sdk][2021-07-08 21:58:21][I] Stopping container "kelvin-bridge-opcua-client:1.0.4"
[kelvin.sdk][2021-07-08 21:58:25][R] Overriding existing configuration with "/home/joao/workspace/flight/control-frame/opcua-app/opcua_client_config.yaml"
[kelvin.sdk][2021-07-08 21:58:25][R] Application successfully launched: "kelvin-bridge-opcua-client:1.0.4"
[ApplicationEngine.cpp:  26:I] - Loading configuration file: /opt/kelvin/app/app.yaml
  [...]
[kelvin_bridge_opcua_client.cpp: 200:D] - Connecting to opcua server 'opc.tcp://kelvin-opcua-demo-server.app:48010'
[        CFClient.cpp:  94:I] - Security settings match for server 'opc.tcp://kelvin-opcua-demo-server.app:48010'
[        CFClient.cpp: 123:D] - Connecting with anonymous user token 
[CFConnectionStatusCallback.cpp:  27:I] - Connection status changed; id: 0  status: Connected
[          Poller.cpp:  70:I] - Successful poller: 10.000000 secs (fd: 14)
[   UploadManager.cpp:  64:D] - Registered channel 'humidity' to upload historic data
[         Runtime.cpp: 113:D] - Registered metric humidity/airconditioner_1 to upload
[kelvin_bridge_opcua_client.cpp: 249:D] - polling metrics
[kelvin_bridge_opcua_client.cpp: 274:D] - Metric 'humidity': 59.987679
[         Runtime.cpp: 532:D] - publishing:  humidity
  [...]

Configurating¶

There are two groups of configurations: the app configuration and the metric configuration. The configurations specific for a kelvin bridge application go under the app:bridge:configuration key of its configuration file, while specific configurations for metrics go under the configuration key for each metric in the app:bridge:metrics_map.

Metrics mapping¶

The metrics map will map the Modbus addresses to the inputs and outputs of the application.

Each metric has the following general configurations:

Name	Description	Default/Required
`name`	The metric name	Required
`asset_name`	The asset name associated to the metric name	Required
`data_type`	The data type of the metric	Required
`access`	Whether the metric is `RO` (read-only) or `RW` (read-write)	Default: `RO`

Then under configuration we have metric configurations specific for the kelvin-bridge-opcua-client:

Name	Description	Default/Required
`node`	The opcua node-id of the metric	Required
`polling_rate`	The polling period in seconds	Required
`protocol_type`	The type of the metric in the opcua server	Required
`scale_multiplier`	An optional multiplier	Optional

Example

app:
  bridge:
    # ...

    metrics_map:
      - name: humidity
        asset_name: airconditioner_1
        data_type: raw.float32
        configuration:
          node: ns=3;s=AirConditioner_1.Humidity
          polling_rate: 10
          protocol_type: float32
          scale_multiplier: 10

      - name: humidity_setpoint
        asset_name: airconditioner_1
        data_type: raw.int32
        access: RW
        configuration:
          node: ns=3;s=AirConditioner_1.HumiditySetpoint
          polling_rate: 10
          protocol_type: int32

General configurations¶

General configurations go under app:bridge:configuration and are the following:

Name	Description	Default/Required
`read_timeout`	The timeout for read requests (integer in seconds)	Default: `10`
`write_timeout`	The timeout for write requests (integer in seconds)	Default: `10`

Connection configurations¶

The connection configurations go under app:bridge:configuration:connection and are the following:

Name	Description	Default/Required
`endpoint`	Endpoint of the server to connect to, eg `opc.tcp://localhost`	Required
`port`	OPCUA port of the server, eg `48010`	Required
`verify_ssl`	true/false; if true verify server identity before connecting	Default: false
`server_cert`	base64 of the server certificate in .der format, used to verify server identity.	Required if `verify_ssl: true`
`message_security`	message security mode to be used, available options are: `none`, `Sign`, `SignAndEncrypt`	Required
`security_policy`	security policy to be used, available options are: `none`, `Basic256Sha256`, `Aes128_Sha256_RsaOaep`, `Aes256_Sha256_RsaPss`	Required

Tip

If verify_ssl is true, the server certificate can also be mounted as a volume in /opt/kelvin/app/pkiclient/trusted/certs/

Authentication configurations¶

The authentication configurations go under app:bridge:configuration:authentication and are the following:

First, we specify the authentication type:

Name	Description	Default/Required
`type`	Authentication type, available options are `none`, `credentials`, `certificate`	Required

Then, if authentication type is credentials or certificate, that key is required with its specific configurations:

Authentication `credentials`¶

Name	Description	Default/Required
`username`	Plain text for the username	Required
`password`	Plain text (preferably use a kelvin secret) for the password	Required

Example

app:
bridge:
  # [...]
  configuration:
    authentication:
      type: credentials
      credentials:
        username: demo
        password: demo

Authentication `certificate`¶

Name	Description	Default/Required
`user_cert`	Path to the certificate file in .der format or the base64 of the application authentication certificate in .der format	Required
`user_key`	Path to the key pair file in .pem format or the base64 of the application authentication key pair in .pem format	Required
`key_password`	Plain text (preferably use a kelvin secret) for the key pair password	Optional

Note

user_cert and user_key should be mounted as volumes in the directory specified in the respective keys

Example

Here's an example of a full configuration of a kelvin-bridge-opcua-client application, followed by a brief explanation of each key:

app:
  bridge:
    configuration:
      read_timeout: 10
      write_timeout: 10

      connection:
        endpoint: opc.tcp://localhost
        port: 48010
        verify_ssl: false   # optional

        security_policy: none # none / Basic256Sha256 / Aes128_Sha256_RsaOaep / Aes256_Sha256_RsaPss
        message_security: none # none / Sign / SignAndEncrypt

        authentication:
          type: none # none / credentials / certificate

          credentials:   # only if type = credentials
            username: user
            password: password

          certificate:  # only if type = certificate
            user_cert: user_cert.der  # mounted as a volume in /opt/kelvin/app
            user_key: user_key.pem  # mounted as a volume in /opt/kelvin/app
            key_password: ""  # optional

OPC UA

Overview¶

Retrieving the application¶

Emulating kelvin-bridge-opcua-client¶

Configurating¶

Metrics mapping¶

General configurations¶

Connection configurations¶

Authentication configurations¶

Authentication credentials¶

Authentication certificate¶

Authentication `credentials`¶

Authentication `certificate`¶