OPCHDA

The OIBus agent can receive the following HTTP calls. The agent run a local HDA module through an inter-process communication. To run properly, COM/DCOM must be enabled. The HDA module can be found in the HdaAgent subfolder of the OIBus Agent and can be run independently though the command line.

OS compatibility

This feature is available only on Windows.

HTTP API

Status

curl --location 'http://localhost:2224/api/opc/id/status'

Connection

curl --location --request PUT 'http://localhost:2224/api/opc/id/connect' \
--header 'Content-Type: application/json' \
--data '{
    "host": "localhost",
    "serverName": "Matrikon.OPC.Simulation"
}'

Read

curl --location --request PUT 'http://localhost:2224/api/opc/id/read' \
--header 'Content-Type: application/json' \
--data '{
    "host": "localhost",
    "serverName": "Matrikon.OPC.Simulation",
    "startTime": "2023-11-02T15:00:00.000Z",
    "endTime": "2023-11-02T16:00:00.000Z",
    "aggregate": "raw",
    "resampling": "none",
    "items": [
        {
            "name": "Random",
            "nodeId": "Random.Int1"
        },
        {
            "name": "Triangle Waves",
            "nodeId": "Triangle Waves.Int1"
        },
        {
            "name": "Saw-toothed Waves",
            "nodeId": "Saw-toothed Waves.Int1"
        }
    ]
}'

Disconnection

curl --location --request DELETE 'http://localhost:2224/api/opc/id/disconnect'

COM/DCOM setup

Background

COM

COM is the standard protocol for communication between objects located on the same computer but which are part of different programs. The server is the object providing services, such as making data available. The client is an application that uses the services provided by the server.

DCOM

DCOM represents an expansion of COM functionality to allow access to objects on remote computers. This protocol allows standardized data exchange between applications from industry, administrative offices and manufacturing. Previously, the applications that accessed the process data were tied to the access protocols of the communication network. The OPC standard software interface allows devices and applications from different manufacturers to be combined in a uniform way.

OPC

The OPC client is an application that accesses process data, messages, and archives of an OPC server. Access is through the OPC software interface. An OPC server is a program that provides standard software interface to read or write data. The OPC server is the intermediate layer between the applications for handling process data, the various network protocols and the interfaces for accessing these data. Only devices with operating systems based on Windows COM and DCOM technology can use the OPC software interface for data exchange.

DCOM connectivity

This page gives some hints on how to set up a communication with COM/DCOM to an OPCHDA server. However, in industrial context, it is often the responsibility of the IT team to correctly set the permissions, firewall and Windows configuration.

Windows settings (client)

Client machine settings

Follow these steps to enable COM/DCOM communications from the client. First, open the Component services, and access the Properties of the computer.

Be sure to enable Distributed COM on this computer (on the Default Properties tab).

On the COM Security tab, edit default Launch and Activation Permissions.

On the Launch and Activation Permissions window, allow the following permissions:

• Local Launch
• Remote Launch
• Local Activation
• Remote Activation

Test communication

DCOM uses port 135 of the HDA server to exchange with the client. To do so, it is interesting to use the tnc command of the Windows Powershell installed as standard. Below, a test that fails (because of the firewall) then a test that succeeds:

tnc localhost -port 135

If you have a communication problem, see the firewall configuration section which is probably the source of the problem.

Authentication

An OPCHDA client program will communicate with the DA/HDA server with the IP address or hostname of the server followed by the "progId" of the server. It will then have to be identified at the Windows level with a name and a password which are (by default) those of the user who launches the client program. This user must therefore be known on the HDA server as well. You must therefore either:

• Create a user with the same password on the HDA server (assuming it is accessible)
• Be part of the same domain (so the user is accessible from all computers in the domain)

Important

The user must be a member of the Distributed COM Users group

Service

If the program runs through a service (such as OIBus), go to the Service manager window, and right-click on the service. Then click on Launch as user.

Firewall configuration

In case of communication issue, the most likely cause is the configuration of a firewall between the two computers and/or at the hosting company in the case of machines on the cloud. On a Windows server, it is possible to configure the firewall by adding a rule on port 135.

In the case of a server hosted by Lightsail, there is an additional firewall in which a custom rule must be configured for port 135.

OPCEnum tool

The OPC Foundation has provided a tool to allow OPCHDA clients to locate servers on remote nodes, without having information about those servers in the local registry. This tool is called OPCEnum and is freely distributed by the OPC Foundation. The PI OPCHDA interface installation installs OPCEnum as well. The primary function of OPCEnum is to inform or request information from other instances of OPCEnum about existing OPCHDA Servers on the local system. When OPCEnum is installed, it grants Launch and Access DCOM permission to Everyone and sets the Authentication level to NONE. This allows access to any user who can log on to the system. The permissions can be changed using dcomcnfg.exe.

RPC unavailable

If the RPC server is unavailable, try again testing COM/DCOM communication testing COM/DCOM communication and check your firewall.

Access denied

Access rights can be diagnosed using the server security log. If the following error happens, check the user and its password created on the HDA server and that the user is in the Distributed COM Users group on the HDA server.

Server settings

Check on the server machine if DCOM is enabled for the OPC Server application by opening the Component Service window. Here is an example with MatrikonOPC Server.

HDA module

The agent is an executable that requires the following DLLs to run:

• CommandLine.dll
• Newtonsoft.Json.dll
• OpcComRcw.dll
• OpcNetApi.Com.dll
• OpcNetApi.dll

Several actions are possible:

• ping: to check connection and gives server information
• catalog: to list available tags and store them in a CSV file
• bulk: to request history and store it in one file per tag

The following options are available for all commands:

-h --host                   Host name (or IP address).
-s --server                 HDA Server name (ex: Matrikon.OPC.Simulation.1)
-l --consoleLevel           Verbosity level for Console (error, warning, info, debug, trace). Default debug
-x --fileLevel              Verbosity level for File (error, warning, info, debug, trace). Default debug

ping

The following option is available:

-i --infos              Display supported aggregates and attributes from the server. Default: false

Usage

.\HdaAgent.exe ping -h localhost -s Matrikon.OPC.Simulation -i

The ping command with the -i option returns three messages from the Matrikon simulation server:

Status infos:

{
    "VendorInfo": "Matrikon Inc +1-780-945-4011 http://www.matrikonopc.com",
    "ProductVersion": "1.7.7433",
    "ServerState": 1,
    "StatusInfo": "",
    "StartTime": "2022-05-16T14:27:46.3709266+00:00",
    "CurrentTime": "2022-08-02T09:18:29.5739742+00:00",
    "MaxReturnValues": 0
}

Supported aggregates

[
    {
        "ID": 1,
        "Name": "INTERPOLATIVE",
        "Description": "Retrieve interpolated values."
    },
    {
        "ID": 4,
        "Name": "TIMEAVERAGE",
        "Description": "Retrieve the time weighted average data over the resample interval."
    },
    {
        "ID": 7,
        "Name": "MINIMUMACTUALTIME",
        "Description": "Retrieve the minimum value in the resample interval and the timestamp of the minimum value."
    },
    {
        "ID": 8,
        "Name": "MINIMUM",
        "Description": "Retrieve the minimum value in the resample interval."
    },
    {
        "ID": 9,
        "Name": "MAXIMUMACTUALTIME",
        "Description": "Retrieve the maximum value in the resample interval and the timestamp of the maximum value."
    },
    {
        "ID": 10,
        "Name": "MAXIMUM",
        "Description": "Retrieve the maximum value in the resample interval."
    }
]

Supported types:

[
    {
        "ID": 1,
        "Name": "DATA_TYPE",
        "Description": "Data type",
        "DataType": "System.Int16, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
    },
    {
        "ID": 2,
        "Name": "DESCRIPTION",
        "Description": "Item Description",
        "DataType": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
    },
    {
        "ID": 11,
        "Name": "NORMAL_MAXIMUM",
        "Description": "High EU",
        "DataType": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
    },
    {
        "ID": 12,
        "Name": "NORMAL_MINIMUM",
        "Description": "Low EU",
        "DataType": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
    },
    {
        "ID": 13,
        "Name": "ITEMID",
        "Description": "Item ID",
        "DataType": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
    },
    {
        "ID": -5,
        "Name": "TRIANGLE",
        "Description": "Triangle Wave",
        "DataType": "Opc.Type, OpcNetApi, Version=2.1.0.0, Culture=neutral, PublicKeyToken=9a40e993cbface53"
    },
    {
        "ID": -4,
        "Name": "SQUARE",
        "Description": "Square Wave",
        "DataType": "Opc.Type, OpcNetApi, Version=2.1.0.0, Culture=neutral, PublicKeyToken=9a40e993cbface53"
    },
    {
        "ID": -3,
        "Name": "SAWTOOTH",
        "Description": "Saw-toothed Wave",
        "DataType": "Opc.Type, OpcNetApi, Version=2.1.0.0, Culture=neutral, PublicKeyToken=9a40e993cbface53"
    },
    {
        "ID": -2,
        "Name": "RANDOM",
        "Description": "Random",
        "DataType": "Opc.Type, OpcNetApi, Version=2.1.0.0, Culture=neutral, PublicKeyToken=9a40e993cbface53"
    },
    {
        "ID": -1,
        "Name": "BUCKET",
        "Description": "Bucket Brigade",
        "DataType": "Opc.Type, OpcNetApi, Version=2.1.0.0, Culture=neutral, PublicKeyToken=9a40e993cbface53"
    }
]

catalog

HdaAgent Catalog creates a csv file catalog.csv using the browse API.

The program displays information about the server (API ServerStatus), Aggregates (getAggregates) and Attributes (getAttributes) as JSON string in the console.

The following options are available:

-i --includesAll        Includes all Items in the server (i.e. folders). Default: false
-f --file               Name of the output folder. Default: catalog.csv

Basic usage

.\HDAAgent.exe catalog -h localhost -s Matrikon.OPC.Simulation

Name,Address
"ArrayOfReal8","Bucket Brigade.ArrayOfReal8"
"ArrayOfString","Bucket Brigade.ArrayOfString"
...

Includes all and specific file

.\HDAAgent.exe catalog -h localhost -s Matrikon.OPC.Simulation --includesAll --file myFile.csv

Name,Address,isItem
"Root","",False
"Simulation Items,"Simulation Items",False
"Bucket Brigade","Bucket Brigade",False
"ArrayOfReal8","Bucket Brigade.ArrayOfReal8",True
"ArrayOfString","Bucket Brigade.ArrayOfString",True
...

bulk

The following options are available:

-b --startTime          Start Time of the history      
-e --endTime            End Time of the history
-d --delay              Throttle: add a delay between requests to minimize load on HDA Servers (in ms)
-m --max                Maximum number of values returned in a request. Defaut 0 (no maximum)
-o --output             Name of the output folder. Default current folder
-c --catalog            Name of the catalog file listing the tags
-a --aggregate          Aggregate value. RAW=0, TOTAL=2, AVERAGE=3, MINIMUM=8, MAXIMUM=10, START=11, END=12. Default 0
-i --interval           Interval (in second) if an aggregate is requested

Basic usage

Request raw values from Matrikon.OPC.Simulation server located on localhost, for points listed in catalog.csv between 2022-01-01 00:00:00 and 2022-02-01 00:00:00.

.\HdaAgent.exe bulk -h localhost -s Matrikon.OPC.Simulation -c catalog.csv -b "2022-01-01 00:00:00" -e "2022-02-01 00:00:00" -a 0

With aggregates

Request by group intervals of 60s (-i 60) the last value (-a 12) of each group for points listed in catalog.csv from Matrikon.OPC.Simulation server located on localhost, between 2022-01-01 00:00:00 and 2022-02-01 00:00:00. Display all logs in the console with trace

.\HdaAgent.exe bulk -h localhost -s Matrikon.OPC.Simulation -c catalog.csv -b "2022-01-01 00:00:00" -e "2022-02-01 00:00:00" -a 12 -i 60 -l trace