OPC DA Agent Installation Guide

This guide details how to retrieve, install, and configure the MaestroHub OPC DA Agent, which is required for the OPC DA Connection to work.

Obtaining the Agent

The MaestroHub OPC DA Agent Executable can be obtained by downloading through this MaestroHub portal website 'https://portal.maestrohub.com/downloads/plugins/'.

System Requirements & Prerequisites

Before installing the agent, ensure your system meets the following requirements:

• OS: Windows 10 (Version 1607+) or Windows Server 2016+
• Runtime: .NET 8 (included in the self-contained build, no separate installation required)
• OPC DA Server: Any OPC DA 2.05a or 3.0 compliant server installed on the same machine.

Windows COM/DCOM Configuration

It is critical that the OPC DA Agent runs on the same machine as the target OPC DA Server(s). Proper COM/DCOM configuration is required to allow the agent to communicate with local OPC servers.

Summary of Required Settings:

1. DCOM Enabled: Ensure "Enable Distributed COM on this computer" is checked in Component Services (dcomcnfg).
2. Authentication Level: Set default authentication to Connect.
3. Impersonation Level: Set default impersonation to Identify.
4. Permissions:
   • Ensure the user account claiming the agent process (and potentially SYSTEM or Interactive depending on how you run it) has Local Launch, Local Activation, and Local Access permissions in COM Security.
   • Check the specific DCOM configuration for your target OPC Server (under DCOM Config) to ensure it allows access to the user running the MaestroHub Agent.

Configuration

The agent is configured via the appsettings.json file located in the same directory as the executable. You can configure network settings, security, and performance limits.

Default Configuration

{
  "AgentSettings": {
    "Port": 45281,
    "ApiToken": "",
    "MaxSubscriptions": 10000,
    "MaxGroups": 100,
    "EnableTLS": false,
    "TlsCertPath": null,
    "TlsCertPassword": null,
    "MaxMessageSizeKB": 1024,
    "BrowseLimit": 5000,
    "DefaultUpdateRateMs": 1000,
    "DefaultDeadbandPercent": 0.0
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Configuration Parameters

Parameter	Default	Description
Port	45281	The secure WebSocket port the agent listens on. Ensure this port is allowed in Windows Firewall.
ApiToken	""	A secure token for authentication. See "generating a secure token" below.
MaxSubscriptions	10000	Maximum number of monitored items allowed.
MaxGroups	100	Maximum number of subscription groups allowed.
EnableTLS	false	Set to true to enable WSS (WebSocket Secure). Requires valid certificate path.
BrowseLimit	5000	Max nodes to return in a single browse request to prevent overloading.

Generating a Secure Token

For security, you must generate a strong API Token and add it to the ApiToken field in appsettings.json. You can generate a random secure token using PowerShell:

[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 }) -as [byte[]])

Copy the output string and paste it into the ApiToken field. Use this same token when configuring the connection in MaestroHub.

Running the Agent

1. Open Command Prompt or PowerShell as Administrator (recommended to ensure access to system services/COM).

2. Navigate to the directory containing the agent.

3. Run the executable:

   .\MaestroHubDaAgent.exe

4. Verify the output logs indicate the server has started and is listening on the configured port (default 45281).

Once the agent is running, you can create an OPC DA connection in MaestroHub and perform operations such as Read, Write, Browse, and Subscribe.